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ACTIVE DEBUGGING ENVIRONMENT FOR APPLICATIONS CONTAINING 
COMPILED AND INTERPRETED PROGRAMMING LANGUAGE CODE 

RELATED APPLICATIONS 

This Application is a Cont i nuation^n - Part o f continuation of U.S. Patent 
5 Application corial numbor 08/81 5,71 O Serial No. 09/016,760, filed January 30, 
1998, hereby incorporated by reference, which is a continuation-in-part of U.S. 
Patent Application Serial No. 08/815,719, filed March 12, 1997, the text of which 
i shereby incorporated by referenc e to th e s am e e xt e nt a s if th e text wh e r e pr e sont 
h e r ei n. — reference. 

1 0 COPYRIGHT AUTHORIZATION 

A portion of the disclosure within this document contains material that is 
subject to copyright protection. The copyright owner has no objection to the 
reproduction of copyright protected materials by any person that is doing so within 
the context of this patent document as it appears in the United States Patent and 
1 5 Trademark Office patent file or records, but the copyright owner otherwise 
reserves all copyright rights whatsoever. 

FIELD OF THE INVENTION 

This invention relates to programming language debugging tools, and in 
particular, to an active debugging environment that is programming language 
20 neutral and host neutral for use in debugging any of a variety of disparate 

compiled and/or interpreted programming languages that may exist individually or 
in combination within a given application. 

PROBLEM 

The end user of a modern software product sees and uses an application 

25 that was created by an application developer. For purposes of this discussion, an 
application is a computer program written in any of a plurality of programming 
languages. Typically, a computer program contains some original program code 
and certain pre-existing or "canned" components that include, but are not limited 
to, modules, libraries, sub-routines, and function calls. The pre-existing 
30 application components are used where ever possible to limit the number of 
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mistakes that are introduced into the application during development, and to 
minimize the amount of overall effort required to create the application. 

As the number of applications and their components have increased, and 
the number of different programming languages used to generate the applications 
5 have increased, so also has the need grown for applications to expose their 
internal services to other applications in a consistent manner independent of the 
underlying programming languages involved. This need for exposing internal 
services of various applications in a universal manner is referred to as providing 
programmability. 

10 Existing program architectural models such as the Component Object 

Model (COM) have greatly contributed to programmability across different 
applications. The COM model establishes a common paradigm for interactions 
and requests among different applications regardless of the programming 
languages or components involved. With COM, for example, an Internet web 

1 5 page application can be created that calls on only certain of the components of a 
word processing application, a spread sheet application, and a database 
application, that are needed to complete the web page application without 
including the entire bulk of each of the word processing, spread sheet, and 
database features within the web page application. 

20 However, one problem that results from creating an application that 

includes multiple program components from many different programming 
language sources, is debugging. A first and third program component in an 
application may have originated from two different compiled language sources 
and a second and fourth program component in an application may have 

25 originated from two different interpretive language sources. Not only is there 
historically a fundamental difference in the implementation of a debugger for a 
compiled programming language versus an interpreted programming language, 
each programming language can have its own proprietary interfaces and other 
features that make debugging the aggregate application a difficult and/or 

30 impossible task. 

For purposes of this document, a compiled programming language is 
considered a native machine code compilable programming language having a 
specific target platform. Examples of compiled programming languages include, 
but are not limited to, C and C++. Alternatively, an interpreted programming 
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language is a run-time bytecode interpreted or source code interpreted 
programming language that operates under control of a master within a given 
application. Examples of interpreted programming languages include Visual 
Basic, Visual Basic for Applications (VBA), Visual Basic Script, Java, JavaScript, 
5 Perl, and Python. The Java programming language is included in the category of 
interpreted programming languages for purposes of this document even though 
Java is compiled from source code to produce an object and there is no access to 
the Java source during run time. One key reason Java is included is because the 
compiled Java object is fundamentally a bytecode object that requires a language 

10 engine rather than the traditional machine code link, load, and execute steps. 

One example of a compiled programming language debugger limitation is 
that they require knowledge of the static environment from which the run-time 
object code was generated. The static environment of a compiled programming 
language includes the source code and the corresponding object code. A 

1 5 debugger for a compiled programming language performs the work of generating 
a mapping of the structures between the source code and the object code prior to 
executing the object being debugged, and the debugger requires that the source 
code and object code remain consistent throughout the debug process. Any 
changes to either the source code and/or the object code render the debug 

20 mapping and subsequent debugging capability unsound. For this reason, 

compiled programming language debuggers do not tolerate run time changes to 
code and the debugger for one compiled programming language is not functional 
for any other programming language. 

Alternatively, interpreted programming languages are more flexible in that 

25 they are run-time interpreted by a programming language engine that does not 
require a static source code or object code environment. However, interpreted 
programming language debuggers do not accommodate compiled programming 
language debugging and are often functional with only one interpreted 
programming language. 

30 Another problem with compiled programming language debuggers is that 

they only function under known predefined run-time conditions with a specific 
operating environment. However, even under these constraints existing compiled 
programming language debuggers are only aware of predefined host application 
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content that is made available to the debugger prior to run time, but the debuggers 
have no run-time knowledge of host application content. 

One solution to the difficulty with debugging applications that contain 
disparate code from compiled programming languages and/or interpreted 
5 programming languages is to limit the developer to using only one programming 
language for an application. However, this solution is undesirable because no 
one programming language is ideal for every application. Further, this solution is 
unreasonable because the demands of present day Internet web page 
programming, as well "as the general customer/developer demands in the 

10 computing industry, require multi-language extensibility. 

For these reasons, there exists an ongoing need for a debugging 
technology that facilitates efficient programmability by way of programming 
language, host application, and operating environment independence. A system 
of this type has heretofore not been known prior to the invention as disclosed 

1 5 below. 

SOLUTION 

The above identified problems are solved and an advancement achieved in 
the field of programming language debuggers due to the active debugging 
environment of the present invention for applications containing compiled and 

20 interpreted programming language code. The active debugging environment 

facilitates content rich run-time debugging in an active debug environment even if 
a mixture of compiled and interpreted programming languages exist within the 
application being debugged. One purpose of the active debugging environment is 
to provide an open and efficiently deployed framework for authoring and 

25 debugging language neutral and host neutral applications. 

In the context of the present discussion, language neutral means that a 
debugging environment exists that transparently supports multi-language program 
debugging and cross-language stepping and breakpoints without requiring specific 
knowledge of any one programming language within the environment. Host 

30 neutral, also referred to as content-centric, means that the debugging environment 
can be automatically used with any active scripting host such that the host 
application has control over the structure of the document tree presented to the 
debug user, including the contents and syntax of coloring of the documents being 
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debugged. In addition, the debugging environment provides debugging services 
that include, but are not limited to, concurrent host object model browsing beyond 
the immediate run-time scope. Host document control allows the host to present 
the source code being debugged in the context of the host document from which it 
5 originated. Further, the language neutral and content-centric host neutrality, 

facilitates a developer transparent debugging environment having multi-language 
extensibility, smart host document and application context management, and 
virtual application discoverability and dynamicness. 

Discoverability means the ability for the debugging environment to be 

10 started during program run-time and immediately step into a running application 
with full knowledge of the executing program's context and program execution 
location. Dynamicness means the concept of flexible debugging where there is no 
static relationship between the run-time environment at the beginning of program 
execution and the run-time environment at some later point in program execution. 

15 In other words, script text can dynamically be added to or removed from a running 
script with the debugging environment having immediate and full knowledge of the 
changes in real time. 

Key components of the active debugging environment include, but are not 
limited to, a Process Debug Manager (PDM) that maintains a catalog of 

20 components within a given application, and a Machine Debug Manager (MDM) 
that maintains a catalog of applications within a virtual application. The active 
debugging environment components work cooperatively with any replaceable 
and/or generic debug user interface that support typical debugging environment 
features. The active debugging environment also cooperatively interacts with a 

25 typical active scripting application components that include, but are not limited to, 
at least one language engine for each programming language present in a given 
script, and a scripting host. 

The method for debugging a multiple language application in an active 
debugging environment includes, but is not limited to, defining a content centric 

30 host, defining a language neutral debugging environment, generating a virtual 
application that includes the multiple compiled and interpretive programming 
language statements and related programming language context, and executing 
the virtual application on the content centric host under control of the language 
neutral active debugging environment. 
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Defining a content centric host includes establishing a language engine 
component for each unique programming language associated with the multiple 
compiled and/or interpreted programming language statements. In addition, the 
language engine component includes programming language specific mapping 
5 and debugging features. Defining the content centric host further includes 
coordinating in-process activities of the content centric host with each of the 
language engine component and the language neutral debugging environment. 
Defining an active debugging environment includes establishing a PDM and an 
MDM as the core components to facilitate debugging by way of a variety of 

10 existing language engines and debug user interfaces, and to coordinate language 
neutral and host neutral communications between the active debugging 
environment and the content centric host during debug operations. 

Additional details of the present invention will become apparent and are 
disclosed in the text accompanying FIGs. 1-7 as set forth below. Appendix A is 

1 5 included to disclose specific details of active scripting interfaces used in one 

example of a run-time implementation. Appendix B is included to disclose specific 
details of interfaces used in one example of an active debugging environment 
implementation. 

20 BRIEF DESCRIPTION OF THE DRAWINGS 

FIG. 1 illustrates an example of a computing system environment example 
in block diagram form on which the claimed invention can be implemented; 
FIG. 2 illustrates a standard object interface example in block diagram 

form; 

25 FIG. 3 illustrates a scripting architecture overview and operational example 

in block diagram form; 

FIG. 4 illustrates an active debugging environment example in block 
diagram form; 

FIG. 5 illustrates an overview of the active debugging operational steps in 
30 flow diagram form; 

FIG. 6 illustrates operational details of the run time environment for a virtual 
application in flow diagram form; and 

FIG. 7 illustrates details of the active debugging environment operational 
steps in flow diagram form. 
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DETAILED DESCRIPTION 

Computing System Environment - FIG. 1 

FIG. 1 illustrates an example of a computing system environment 100 on 
which the claimed invention could be implemented. The computing system 
5 environment 100 is only one example of a suitable computing environment for the 
claimed invention and is not intended to suggest any limitation as to the scope of 
use or functionality of the claimed invention. Neither should the computing 
environment 100 be interpreted as having any dependency or requirement relating 
to any one or combination of components illustrated in the exemplary computing 

10 system environment 100. 

The claimed invention is operational with numerous other general purpose 
or special purpose computing system environments or configurations. Examples 
of well known computing systems, environments, and/or configurations that may 
be suitable for use with the claimed invention can include, but are also not limited 

15 to, a general purpose Personal Computer (PC), hand-held or lap top computers, 
multi-processor systems, microprocessor-based systems, programmable 
consumer electronics, network computers, Personal Communication Systems 
(PCS), Personal Digital Assistants (PDA), minicomputers, mainframe computers, 
distributed computing environments that include any one or more of the above 

20 computing systems or devices, and the like. 

The claimed invention may also be described in the general context of 
computer-executable instructions that are executable on a PC. Such executable 
instructions include the instructions within program modules that are executed on 
a PC for example. Generally, program modules include, but are not limited to, 

25 routines, programs, objects, components, data structures, and the like that 

perform discrete tasks or implement abstract data types. The claimed invention 
may also be practiced in distributed computing environments where tasks are 
performed by remote processing devices that are linked through a 
communications network. In a distributed computing environment, program 

30 modules may be located in both local and remote memory devices. 

The exemplary computing system environment 100. is a general purpose 
computing device such a PC 1 10. Components of PC 110 include, but are not 
limited to, a processing unit 120, a system memory 130, and a system bus 121. 
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The system bus 121 communicatively connects the aforementioned components 
and numerous other cooperatively interactive components. 

Processing unit 120 is the primary intelligence and controller for PC 1 10 
and can be any one of many commercially available processors available in the 
5 industry. System bus 121 may be any combination of several types of bus 

structures including, but not limited to, a memory bus, a memory controller bus, a 
peripheral bus, and/or a local bus. System bus 121 , also referred to as an 
expansion bus or I/O channel, can be based on any one of a variety of bus 
architectures including, but not limited to, Industry Standard Architecture (ISA) 

10 bus, Micro Channel Architecture (MCA), Enhanced ISA (EISA), Video Electronics 
Standards Association (VESA) local bus, and Peripheral Component Interconnect 
(PCI) also known as Mezzanine bus. 

System memory 130 is a volatile memory that can include a Read Only 
Memory (ROM) 131 and/or a Random Access Memory (RAM) 132. ROM 131 

15 typically includes a Basic Input/Output System (BIOS) 133. BIOS 133 is 
comprised of basic routines that control the transfer of data and programs 
between peripheral non-volatile memories that are accessible to PC 1 10 during 
start-up or boot operations. RAM 132 typically contains data and/or programs that 
are immediately accessible to and/or presently being operated on by processing 

20 unit 120. Types of data and/or programs in RAM 132 can include operating 
system programs 134, application programs 135, other program modules 136, 
and program data 137. 

Other components in PC 110 include numerous peripheral devices that are 
accessible to processing unit 120 by way of system bus 121 . The numerous 

25 peripheral devices are supported by appropriate interfaces that can include a first 
non-volatile memory interface 140 for non-removable non-volatile memory device 
support, a second non-volatile memory interface 150 for removable non-volatile 
memory device support, a user input interface 160 for serial device support, a 
network interface 170 for remote device communication device support, a video 

30 interface 190 for video input/output device support, and an output peripheral 
interface 195 for output device support. 

Examples of a non-removable non-volatile memory device can include a 
magnetic disk device 141 or other large capacity read/write medium such as an 
optical disk, magnetic tape, optical tape, or solid state memory. Types of data 
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often stored on a non-removable non-volatile memory device include persistent 
copies of programs and/or data being used and/or manipulated in RAM 132 such 
as operating system programs 144, application programs 145, other program 
modules 146, and program data 147. 
5 One example of a removable non-volatile memory device can include a 

magnetic floppy disk device or hard disk device 151 that accepts removable 
magnetic media 152. Another example of a removable non-volatile memory 
device can include an optical disk device 155 that accepts removable optical 
media 156. Other types of removable media can include, but are not limited to, 

10 magnetic tape cassettes, flash memory cards, digital video disks, digital video 
tape, Bernoulli cartridge, solid state RAM, solid state ROM, and the like. 

User input interface 160 supports user input devices that can include, but 
are not limited to, a pointing device 161 commonly referred to as a mouse or 
touch pad, and a keyboard 162. Other user input devices can include, but are not 

15 limited to, a microphone, joystick, game pad, neuro-stimulated sensor, and 

scanner, and may require other interface and bus structures such as a parallel 
port, game port or a Universal Serial Bus (USB) for example. 

User input/output devices supported by video interface 190 can include a 
display monitor 191 or a video camera. Output peripheral interface 195 supports 

20 output devices such as printer 196 and speakers 197. 

Network interface 170 supports communications access to a remote 
computing facility such as remote computer 180 by way of Local Area Network 
(LAN) 171 and/or Wide Area Network (WAN) 173, or other Intranet or Internet 
connection. Other remote computing facility types for remote computer 180 can 

25 include, but are not limited to, a PC, server, router, printer, network PC, a peer 
device, or other common network node. A remote computer 180 can typically 
include many or all of the components described above for PC 110. 
Modulator/Demodulator (MODEM) 172 can also be used to facilitate 
communications to remote computer 180. Types of programs and/or data 

30 accessible from remote memory device 181 on remote computer 180 can include, 
but are not limited to, remote application programs 185. 

Definitions 

The following terms and concepts are relevant to this disclosure and are 
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defined below for clarity. 



Term 



Definition 



Code Context 



Code object 



Context 



Debug Event 



Debugger IDE 



Expression 
Context 



A representation of a particular location in running code of a 
language engine, such as a virtual instruction pointer. 

An instance created by a script host that is associated with a 
named item, such as the module behind a form in Visual Basic, or 
a C++ class associated with a named item. 

An abstraction also referred to as document context that 
represents a specific range in the source code of a host 
document. 



A run-time flow altering condition, such as a breakpoint, that is set 
in a virtual application by a debugging environment user and 
managed by the active debugging environment that controls the 
running of the virtual application. Debug events are defined by 
the active debugger. 

A replaceable component of the active debugging environment 
that supports an Integrated Development Environment (IDE) 
debugging User Interface (Ul), and the primary component that 
communicates with the host application and one or more of the 
language engines. 

A context of a resource, such as a stack frame, in which 
expressions may be evaluated by a language engine. 

Host Application The application or process that hosts one or more language 

engines and provides a scriptable set of objects, also known as 
an object model. 

A replaceable component of the active debugging environment, 
sometimes referred to as a scripting engine, that provides parsing, 
execution, and debugging abstractions for a particular language, 
and implements lactiveScript and/or lactiveScriptParse. 

Machine Debug A key component of the active debugging environment that 



Language 
Engine 



10 



1001/047 | 
Manager maintains a registry of debuggable application processes. 

Named item An object, such as one that supports OLE Automation, that the 

host application deems interesting to a script. Examples include 
the HTML Document object in a Web browser or the Selection 
object in Microsoft Word. 

Object Browsing A structured, language-independent representation of an object 
name, type, value, and/or sub-object that is suitable for 
implementing a watch window user interface. 

A key component of the active debugging environment that 
maintains a registry of components for a given application that 
include the tree of debuggable documents, language engines, 
running threads, and other application resources. 

A set of instructions that are run by a language engine. A script 
can include, but is not limited to any executable code, piece of 
text, a block of pcode, and/or machine-specific executable byte 
codes. A script is loaded into a language engine by a script host 
by way of one of the Ipersist* interfaces or the lactiveScriptParse 
interface. 



Process Debug 
Manager 



Script 



Script language 
Script host 



Scriptlet 



An interpreted programming language and the language 
semantics used to write a script. 

An application or program that owns the ActiveScripting engine. 
The scripting host implements lactiveScriptSite and optionally 
lactiveScriptSiteWindow. 

A portion of a script that is attached to an object event through 
lactiveScriptParse. An aggregate of scriptlets is a script. 



Standard Object Interface Example - FIG. 2 

FIG. 2 illustrates a standard object interface example 200 in block diagram 
form. The standard object interface example 200 includes a local computing 
device 201 and a remote computing device 202, both of which can be personal 
computers. The remote computing device 202 includes a remote operating 
system 240 and a host process 250. The host process 250 includes at least one 
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application object 251 having multiple interfaces including but not limited to 
interfaces 252-254. Each interface 252-254 is a standard COM interface that 
each exposes at least one method. 

The local computing device 201 includes a local operating system 210, a 
5 first host process 220 and a second host process 230. The local operating 

system 210 includes a plurality of application objects 211-212 each having at least 
one of a plurality of interfaces 214-218. The second host process 230 includes a 
plurality of application objects including 232-233 each having at least one the 
plurality of interfaces 234-238. The first host process 220 includes, but is not 

10 limited to, a plurality of local and/or remote interface calls 221-226 to respective 
interfaces in host processes 250, 230, and local operating system 210 as 
indicated by the directional arrows away from the first host process 220. The 
interface calls 221-226 occur at various points in a script 228 and two of the calls 
222 and 226 result in the downloading of a small section of a foreign program into 

15 the script 228 for execution. The downloaded programs may have originated in 
any compiled or interpreted programming language other than the programming 
language of script 228. Key to each of the above referenced interface calls is 
that they are calls to common interfaces that are made in a common manner from 
any application or process. 

20 Scripting Architecture Overview and Operational Example - FIG. 3 

A scripting language engine interface provides the capability to add 
scripting and OLE Automation capabilities to programs such as applications or 
servers. One example of a scripting language engine interface is embodied in the 
commercially available product known as ActiveX™ Scripting by Microsoft. 

25 ActiveX Scripting enables host computers to call upon disparate language engines 
from multiple sources and vendors to perform scripting between software 
components. The implementation of a script itself including the language, syntax, 
persistent format, execution model, and the like, is left to the script vendor. Care 
has been taken to allow host computers that rely on ActiveX Scripting to use 

30 arbitrary language back-ends where necessary. 

Scripting components fall into at least two categories that include script 
hosts and language engines. A script host creates an instance of a language 
engine and calls on the language engine to run at least one portion of a script. 
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Examples of script hosts can include but are not limited to Internet and Intranet 
browsers, Internet and Intranet authoring tools, servers, office applications, and 
computer games. A desirable scripting design isolates and accesses only the 
interface elements required by an authoring environment so that non-authoring 
5 host computers such as browsers and viewers, and the associated language 
engines can be kept relatively compact. 

FIG. 3 illustrates an operational active scripting architecture example 300 in 
flow diagram form. Examples of active scripting interfaces are disclosed in 
Appendix A. Components of the operational active scripting architecture example 

10 300 include a language engine 301, a host document or application 305, a script 
304, and various object interfaces 310-314 for the language engine 301 and host 
application 305 respectively. The following discussion illustrates the interactions 
between the language engine 301 and the host application 305. 

First, a host application 305 begins operations by creating an instance of 

1 5 the application in a workspace of a computing device. A copy of the host 

application 305 can be obtained from a storage device 306 or other source in any 
manner well known in the art. 

Second, the host application 305 creates an instance of the language 
engine 301 by calling the function CoCreate In stance and specifying the class 

20 identifier (CLSID) of the desired language engine 301 . For example, the Hyper 
Text Markup Language (HTML) browsing component of Internet Explorer receives 
the language engine's class identifier through the CLSID= attribute of the HTML 
<OBJECT> tag. The host application 305 can create multiple instances of 
language engine 301 for use by various applications as needed. The process of 

25 initiating a new language engine is well known in the art. 

Third, after the language engine 301 is created, the host application 305 
loads the script 304 itself into the language engine 301 by way of interface/method 
310. If the script 304 is persistent, the script 304 is loaded by calling the 
IPersist*::Load method 310 of the language engine 301 to feed it the script 

30 storage, stream, or property bag that is resident on the host application 305. 
Loading the script 304 exposes the host application's object model to the 
language engine 301 . Alternatively, if the script 304 is not persistent then the host 
application 305 uses IPersist*::lnitNew or IActiveScriptParse::lnitNew to create a 
null script. As a further alternative, a host application 305 that maintains a script 
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304 as text can use IActiveScriptParse::ParseScriptText to feed the language 
engine 301 the text of script 304 after independently calling the function InitNew. 

Fourth, for each top-level named item 303 such as pages and/or forms of a 
document that are imported into the name space 302 of the language engine 301 , 
5 the host application 305 calls IActiveScript::AddNamedltem interface/method 31 1 
to create an entry in the name space 302. This step is not necessary if top-level 
named items 303 are already part of the persistent state of the previously loaded 
script 304. A host application 305 does not use AddNamedltem to add sublevel 
named items such as controls on an HTML page. Instead, the language engine 

10 301 indirectly obtains sublevel items from top-level items by using the ITypelnfo 
and/or IDispatch interface/method 314 of the host application 305. 

Fifth, the host application 305 causes the language engine 301 to start 
running the script 304 by passing the SCRIPTSTATE_CONNECTED value to the 
IActiveScript::SetScriptState interface/method 31 1 . This call typically executes 

15 any language engine construction work, including static bindings, hooking up to 
events, and code execution similar to a scripted "main()" function. 

Sixth, each time the language engine 301 needs to associate a symbol with 
a top-level named item 303, the language engine 301 calls the 
IActiveScriptSite::Getltemlnfo interface/method 312. The, the 

20 IActiveScriptSite::Getltemlnfo interface/method 312 can also return information 
about the named item in question. 

Seventh, prior to starting the script 304 itself, the language engine 301 
connects to the events of all relevant objects through the IConnectionPoint 
interface/method 313. For example, the IConnectionPoint::Advise(pHandler) 

25 message provides the language engine 301 with a request for notification of any 
events that occur in the host application 305. The IConnectionPoint::Advise 
message passes an object pHandler that can be called when an event occurs in 
the host application 305. Once an event occurs in the host application 305, the 
host application 305 transmits a message to the language engine 301 

30 pdispHandler::lnvoke(dispid) as notice that an event occurred in the host 
application 305. If the event that occurred matches an event that is being 
monitored by the language engine 301, the language engine 301 can activate a 
predetermined response. 

Finally, as the script 304 runs, the language engine 301 realizes references 
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to methods and properties on named objects through the IDispatch::lnvoke 
interface/method 314 or other standard COM binding mechanisms. Additional 
implementation specific details of ActiveX Scripting interfaces and methods are 
disclosed Appendix A. 
5 One purpose of ActiveX is to allow a developer to expose internal objects 

and/or properties of an application as interfaces and methods available to other 
applications. A method is an action which the object can perform, and a property 
is an attribute of the object similar to a variable. The ActiveX interfaces include 
IDispatch which is an interface to manipulate ActiveX objects. This process is 

10 used to get a property, set a property, or call a method. The process uses a late 
binding mechanism that enables a simple non-compiled interpretive language. 
Type information in ActiveX includes ITypelnfo which is used for describing an 
object. A collection of these Typelnfos constitutes a type library, which usually 
exists on a disk in the form of a data file. The data file can be accessed through 

15 ITypeLib and is typically created using MKTypLib. In ActiveX scripting, the type 
information is provided by scripting hosts and objects that are used by the 
scripting hosts. 

Active Debugging Environment - FIG. 4 

20 FIG. 4 illustrates an example of an active debugging environment 400 in 

block diagram form based on the standard object interface example 200 of FIG. 2. 
In the active debugging environment 400 example, the first host process 220 
contains the application 421 that is the debugging target although any application 
in one of the host processes 220, 230, or 250 can be the debugging target if 

25 desired. For example, the host process 250 might include an Internet web page 
application on an Internet server 202, and the host process 220 might include an 
Internet browser application under development on an end user's local machine 
201 . The Internet browser application under development would be the 
debugging target so that the application developer can watch what is happening 

30 as the browser interacts with the remote web page and exercises various features 
and controls of the web page. 

Components of the overall active debugging environment 400 include 
active scripting application components 420, key debugging environment interface 
components that include the PDM 424 and the MDM 41 1 , and the IDE 410 debug 
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interface. It is important to note that the active scripting application components 
420 are standard application components of a product, such as an Internet 
browser, that are shipped to and used by an end user upon general release of a 
version of the product. That the standard application components are designed 
5 with active debugging environment interfaces in mind is transparent to the end 
user of the application. Note also that the IDE 41 0 is an active debugging 
component that is replaceable by any developer wishing to architect a debugging 
interface. The PDM 424 and MDM 41 1 are the fundamental components of the 
active debugging environment 400 with which the active scripting application 
10 components 420 and the IDE 410 must interact to facilitate a functional debugging 
environment. 

The IDE 410 is a debug user interface between the debug user and the 
active debugging environment 400. The typical IDE 41 0 allows a debug user to 
engage in real time document and/or application editing, requesting various views 

15 of the running application, defining breakpoints and other execution control 

management features, requesting expression evaluation and watch windows, and 
browsing stack frames, objects, classes, and application source code. 

One example of debug interfaces for an IDE 410 are disclosed in Appendix 
B. The architecture of an IDE 410 can be designed to support features such as 

20 CModule, CBreakpoint, CApplicationDebugger, and CurStmt. For example, there 
can be one CModule instance per document/application being debugged such 
that the instance is maintained in a doubly-linked list headed by g_pModuleHead. 
Entries in the list can be displayed to the debug user in a selectable Module menu 
and any selected list item would result in document text being displayed in the 

25 richedit control. From the richedit control, the debug user could define set 
breakpoints or user other viewing features. If a debug user were to set a 
breakpoint, one Cbreakpoint instance would be generated and maintained in a 
doubly-linked list headed by the g_pBpHead field of the associated CModule. 
Each breakpoint position could be represented to the debug user as a text range 

30 of the document. One CApplicationDebugger instance would be generated and 
maintained by the application that implements the lApplicationDebugger interface 
so that the CApplicationDebugger could respond to all debug events that occur. 
Finally, the CurStmt could hold the location of the current statement being 
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executed in addition to referencing the thread associated with the present 
breakpoint. 

The Machine Debug Manager (MDM) 41 1 maintains a list of active virtual 
applications and is a central interface between the IDE 410 and the active script 
5 components 420. Virtual applications are collections of related documents and 
code in a single debuggable entity such that separate application components in a 
continuous line of code can share a common process and/or thread. A virtual 
application is the aggregate of multiple applications in multiple programming 
languages. One key role of the machine debug manager is to act as a program 

10 language registry that provides a mapping between a given application in the 
virtual application aggregate and the active debugger IDE 410 that is controlling 
the virtual application during the debug process. The MDM 41 1 eliminates the 
traditional debugging model where the debugger for a given programming 
language only has knowledge of a specific source and object code mapping. 

1 5 Instead, the MDM 41 1 places the burden of language specific details on the 

programming language to determine, for example, the mapping of a breakpoint 
requested by the debug user to a specific instruction in the programming language 
code within a given application. For an interpreted programming language, a 
programming language specific decision is passed through the PDM 424 to an 

20 appropriate language engine 422-423. For a compiled programming language, a 
programming language specific decision is passed through the PDM 424 to a 
library of source and object codes associated with an appropriate language 
engine 422-423. 

The active scripting application components 420 include a script host 421 
25 and at least one language engine 422-423, and each of the at least one language 
engine 422-423 operate in close cooperation with the PDM 424. The PDM 424 
includes a catalog of components within a given application, and acts as an 
interface for all in-process activities and synchronizes the debugging activities of 
the multiple language engines 422-423 such as merging stack frames and 
30 coordinating breakpoints for example. The PDM 424 also maintains a debugger 
thread for asynchronous processing and acts as the communication interface for 
the MDM 41 1 and the IDE 41 0. 

A language engine 422-423 supports a specific language implementation 
and provides specific language features used by the corresponding program 
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language code in the virtual application. Among the specific language features 
are the breakpoint, start, stop, and jump debug implementations, expression 
evaluations, syntax coloring, object browsing, and stack frame enumeration. Each 
language specific feature is unique to a programming language regardless of the 
5 quantity of that programming language that exists in the virtual application. 

The application or script host 421 provides the environment for the 
language engines 422-423. Additional tasks of the script host 421 include 
supporting an object model, providing context for scripts, organizing scripts into 
virtual applications, maintaining a tree of documents being debugged and their 

10 contents, and providing overall document management. An example of a script 
host is an Internet browser such as Internet Explorer or Spruuids. One important 
script host concept is that a host does not necessarily require a design that has 
debugging in mind because it is the programming language that must have been 
created with debugging in mind. For this reason, the script host 421 does not 

1 5 require specific knowledge of any language specific debugging features. Specific 
knowledge of language specific debugging features is the task of the individual 
language engines 422-423 and/or their associated libraries. 

It is also important to note that depending on the design of a script host 
421 , the script host 421 can exist in the active debugging environment 400 as a 

20 smart host or a dumb host. A dumb host is not aware of all available debug 
interfaces because all scripts are separate and/or are managed by language 
engines independently of each other, and no contextual view of source code 
exists. Nevertheless, a dumb host can support self-contained languages such as 
Java and can provide a default virtual application for the current process. 

25 Alternatively, a smart host is aware of the debug interfaces and can group 

program code and documents into a single virtual application to provide visual 
context to embedded languages such as HTML. The smart host takes advantage 
of and supports integrated debugging support across a mixed model of 
programming languages and is generally aware of the context and origin of 

30 individual scripts. Although, a smart host provides a more robust and efficient 
debugging environment, debugging can proceed in kind for a dumb host even if 
with somewhat limited flexibility. 

Active Debugging Environment Operational Steps - FIGs. 5-7 
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FIG. 5 illustrates an example overview of active debugging environment 
operational steps 500 in flow diagram form. The active debugging environment 
operational steps 500 begin at step 508 and represent a high-level view of steps 
involved in the setup and operation of an active debugging environment where 
5 programming language code from multiple compiled and/or interpreted 

programming languages are present in the same virtual application debug target. 

At step 512, the script host 421 generates a virtual application for run time 
execution. The virtual application can contain program language code from only 
single programming language, or the virtual application can contain an aggregate 

10 of programming language code from multiple compiled and/or interpreted 

programming languages. Additional details of step 512 are disclosed in the text 
accompanying FIG. 6. 

At step 521, an active debugging environment is established that controls 
the stepwise flow of a run time script. Key to the active debugging environment 

15 400 being programming language neutral and content-centric host neutral is that 
the programming language debug specifics are embedded in the active scripting 
application components 420 rather than in the debugging tool itself. Key 
responsibilities of the active debugging environment 400 is to facilitate 
programming language neutral and host neutral debugging by interfacing the IDE 

20 410 user interface with the active scripting application components 420 by way of 
the catalog of applications maintained in the MDM 41 1 and the catalog of 
application components in the PDM 424. The MDM 41 1 and the PDM 424 
determine which application and which language engine 422-423 is responsible 
for a given section of program language code in the virtual application as 

25 previously disclosed in the text accompanying FIG. 4. 

At step 530, with the run time environment established and the active 
debug environment in place, the previously generated virtual application is 
executed under the control of the active debugging environment 400. Note that 
during run time of the virtual application at step 538, that the active debugging 

30 environment 400 accommodates the dynamic run-time modification of program 
code in the script without disrupting script execution flow or the active debugging 
operations. One reason this dynamic run-time environment is possible even with 
the existence of compiled programming language segments present, is that each 
programming language segment added to or removed from the running script is 
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accompanied by the necessary language engine support to assist with the 
language specific debug details. 

At step 550, a debug user or application developer interacts with the active 
debugging environment during the debugging process by way of the IDE 410. 
5 Additional details of the debugging process interactions are disclosed in the text 
accompanying FIG. 7. The active debug operational steps 500 end at step 560 at 
the time the application developer chooses to stop the debugging process. 

FIG. 6 illustrates details of the active scripting run-time environment 
operational steps 600 for a virtual application in flow diagram form. The active 

10 scripting run-time environment operational steps 600 begin at step 608 and 

represent the details of step 512 of FIG. 5. Although the text accompanying FIG. 
6 discloses the details of one type of run-time environment for virtual applications, 
the active debugging environment 400 of the present invention is host neutral and 
functions equally well with any COM designed active scripting run-time 

15 environment. 

At step 612, an instance of a script host 421 is created in an application 
220 to manage run-time execution of a virtual application. Along with the script 
host 421 , at least one programming language engine 422-423 is generated for 
each programming language used in an application. At step 622, the multiple 

20 objects within the application are combined into a single virtual application, also 
known as script text. At step 630 the single virtual application is loaded into the 
script host 421 for run-time execution. Processing continues at step 638 by 
returning to step 512 of FIG. 5. 

FIG. 7 illustrates details of debugging operational steps 700 in flow diagram 

25 form in the context of the active debugging environment 400. The debugging 
operational steps 700 begin at step 708 and represent the details of step 550 in 
FIG. 5. At step 712, an active debugging environment 400 is established that 
includes an IDE 410 as a user interface, a MDM 41 1 to catalog applications that 
are present and manage language specific interactions with each target 

30 application, and a PDM 424 to catalog application components and manage 

component specific activities during the debug process. At step 720, the virtual 
application script and the script host 421 are identified and the virtual application 
is run under the control of the active debugging environment 400. Starting a 
virtual application under the control of an active debugging environment means 
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that breakpoints, stepwise code execution, and/or other script flow altering 
activities can be set at will by a human user to alter the run-time script flow as 
desired during the debug process. 

At step 728, one or more event monitoring cases can be set in the active 
5 debugging environment 400 by communicating the event criteria to the 

appropriate active scripting application components 420 by way of the MDM 41 1 
and/or PDM 424, and the IDE 410 user interface. Each event is specific to a 
given portion of the run-time script text even though the script text programming 
language details are transparent to the debug user. Further, the number of event 

10 monitoring cases defined for a given virtual application can be dynamically altered 
as different programming language code sections are downloaded to the script 
host 421 to dynamically become part of the running virtual application. 

If it is determined at decision step 735 that the run-time script text has not 
reached an event being monitored, then the run-time script text continues running 

1 5 at step 735. In the mean time, the debug user is free to carry out other activities 
in the context of the active debugging environment that can include, but are not 
limited to, viewing other documents, the document tree, source code, or even 
make changes to the source code as desired. Alternatively, if it is determined at 
decision step 735 that the run-time script text has reached an event being 

20 monitored, then processing continues at step 742. At step 742, a predefined 

debugging response is activated in response to the occurrence of the monitored 
event. Predefined responses can include, but are not limited to, displaying a 
range of script text that contains a breakpoint, displaying variable or other 
reference contents, and displaying stack pointers, all within the context supported 

25 by the corresponding language engine specific to the immediate programming 

language statements. All communications between the debug user and the script 
host 421 are facilitated by the MDM 41 1 and/or the PDM 424 that process and 
pass requests to an appropriate language engine 422-423 for a response. 
If it is determined at decision step 755 by the debug user that the 

30 debugging process should continue, then processing continues at step 728 as 
previously disclosed. Alternative, if it is determined at decision step 755 by the 
debug user that the debugging process is complete, then the debug 
communicates to the IDE 410 that debug processing should stop and processing 
continues at step 762 by returning to step 550 of FIG. 5. 
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Conclusion 

The present invention is an active debugging environment that is 
programming language independent and host application independent for use in 
5 debugging a mixture of compiled and interpreted programming languages in a 
given application. The programming language and host application independence 
is facilitated by Machine Debug Manager and Process Debug Manager interfaces 
that identify an appropriate language engine and/or application specific 
components that is responsible for unique programming language details. 

1 0 Appendices are attached to this document that disclose examples of active run- 
time script engine interfaces and active debugging environment interfaces. 
Specific active run-time script implementation interfaces are disclosed in Appendix 
A. Specific active debugging environment implementation interfaces are 
disclosed in Appendix B. 

15 Although specific embodiments are disclosed herein, it is expected that 

persons skilled in the art can and will make, use, and/or sell alternative active 
debugging environment systems that are within the scope of the following claims 
either literally or under the Doctrine of Equivalents. 

20 Appendix A: ActiveX Scripting 
Interfaces and Methods 
lActiveScript 

The scripting engine must implement the lActiveScript interface in order to be an 
ActiveX Scripting engine. 

25 



Methods in Vtable Order 



lUnknown methods 


Description 


Query Interface 


Returns pointers to supported interfaces. 


AddRef 


Increments the reference count. 


Release 


Decrements the reference count. 


lActiveScript methods 


Description 


SetScriptSite 


Informs the scripting engine of the lActiveScriptSite 




site provided by the host. 


GetScriptSite 


Retrieves the site object associated with the ActiveX 



22 



1001/047 





Scripting engine. 


SetScriptState 


Puts the scripting engine into the given state. 


GetScriptState 


Retrieves the current state of the scripting engine. 


Close 


Causes the scripting engine to abandon any currently 




loaded script, lose its state, and release any interface 


pointers it has to other objects, thus entering a closed 


state. 


AddNamedltem 


Adds the name of a root-level item to the scripting 




engine's name space. 


AddTypeLib 


Adds a type library to the name space for the script. 


GetScriptDispatch 


Retrieves the IDispatch interface for the methods 




and properties associated with the running script 


itself. 


GetCurrentScriptThread 


Retrieves a scripting-engine-defined identifier for the 


ID 


currently executing thread. 


GetScriptThreadlD 


Retrieves a scripting-engine-defined identifier for the 




thread associated with the given Microsoft Win32® 


thread. 


GetScriptThreadState 


Retrieves the current state of a script thread. 


1 nterru ptScriptThread 


I ■ aril a • f * * X A. 1 1 

Interrupts the execution of a running script thread. 


Clone 


Clones the current scripting engine (minus any 




current execution state), returning a loaded, unsited 


scripting engine in the current thread. 



IActiveScript::AddNamedltem 

HRESULT AddNamedltem ( 

5 LPCOLESTR pstrName, // address of item name 

DWORD dwFlags // item flags 

11 



Adds the name of a root-level item to the scripting engine's name space. A root- 



10 level item is an object with properties and methods, an event source, or both. 
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pstrName 

[in] Address of a buffer that contains the name of the item as viewed from the 
script. The name must be unique and persistable. 
dwFlags 

5 [in] Flags associated with item. Can be a combination of these values: 



Value 


Meaning 


SCRIPTITEM ISPERSISTENT 


Indicates that the item should be saved if 




the scripting engine is saved. Similarly, 
setting this flag indicates that a transition 
back to the initialized state should retain 
the item's name and type information (the 


scripting engine must, however, release 
all pointers to interfaces on the actual 
object). 


SCRIPTITEMJSSOURCE 


Indicates that the item sources events 




that the script can sink. Children 
(properties of the object that are in 
themselves objects) can also source 
events to the script. This is not recursive, 


but it provides a convenient mechanism 
for the common case, for example, of 
adding a container and all of its member 


controls. 


SCRIPTITEM ISVISIBLE 


Indicates that the item's name is 




available in the name space of the script, 
allowing access to the properties, 
methods, and events of the item. 
Because by convention the properties of 
the item include the item's children, all 
child object properties and methods (and 
their children, recursively) will be 
accessible. 


SCRIPTITEM GLOBALMEMBERS 


Indicates that the item is a collection of 
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global properties and methods 
associated with the script. Normally, a 


scripting engine would ignore the object 
name (other than for the purpose of using 


it as a cookie for 

IActiveScriptSite::Getltemlnfo, or for 
resolving explicit scoping) and expose its 
members as global variables and 
methods. This allows the host to extend 


the library (run-time functions and so on) 
available to the script. It is left to the 


scripting engine to deal with name 
conflicts (for example, when two 
SCRIPTITEM GLOBALMEMBERS 


items have methods of the same name), 
although an error should not be returned 
because of this situation. 


SCRIPTITEM NOCODE 


Indicates that the item is simply a name 




being added to the script's name space, 
and should not be treated as an item for 
which code should be associated. For 
example, without this flag being set, 
VBScript will create a separate module 
for the named item, and C++ might 
create a separate wrapper class for the 
named item. 


SCRIPTITEM CODEONLY 


Indicates that the named item represents 




a code-only object, and that the host has 
no lUnknown to be associated with this 
code-only object. The host only has a 
name for this object. In object-oriented 
languages such as C++, this flag would 


create a class. Not all languages support 


this flag. 
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Returns 




S OK 


The named item was successfully added to the script s 




name space. 


E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 



See also IActiveScriptSite::Getltemlnfo 



IActiveScript::AddTypeLib 

HRESULT AddTypeLib ( 



// LIBID of type library 





DWORD dwMaj, 


// 


major version number 




DWORD dwMin, 


// 


minor version number 


10 


DWORD dwFlags 


// 


option flags 



15 



Adds a type library to the name space for the script. This is similar to the 
#include directive in C/C++. It allows a set of predefined items such as class 
definitions, typedefs, and named constants to be added to the run-time 
environment available to the script. 



guidTypeLib 

[in] LIBID of the type library to add. 
20 dwMaj 

[in] Major version number. 
dwMin 

[in] Minor version number. 
dwFlags 

25 [in] Option flags. Can be SCRIPTTYPELIBJSCONTROL, which indicates that 
the type library describes an ActiveX control used by the host. 
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Returns 




S OK 


The specified type library was successfully 




added. 


E UNEXPECTED 


The call was not expected (for example, the 




scripting engine has not yet been loaded or 




initialized). 


TYPE E CANTLOADLIBRARY 


The specified type library could not be 




loaded. 


E INVALIDARG 


An argument was invalid. 



lActiveScript: :Clone 

HRESULT Clone ( 

lActiveScript **ppscript // receives pointer to lActiveScript 

5 ii 



Clones the current scripting engine (minus any current execution state), returning 
a loaded, unsited scripting engine in the current thread. The state of this new 
scripting engine should be identical to the state the original scripting engine would 
10 be in if it were transitioned back to the initialized state. 

ppscript 

[out] Address of a variable that receives a pointer to the lActiveScript interface 
of the unsited, cloned scripting engine. The host must create a site and call 
15 SetScriptSite on the new scripting engine before it will be in the initialized state 
and, therefore, usable. 



The Clone method is an optimization of Persist*: :Save, CoCreatelnstance, and 
IPersist*::Load, so the state of the new scripting engine should be the same as if 
20 the state of the original scripting engine were saved and loaded into a new 

scripting engine. Named items are duplicated in the cloned scripting engine, but 
specific object pointers for each item are forgotten and are obtained with 
Getltemlinfo. This allows an identical object model with per-thread entry points 
(an apartment model) to be used. 
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This method is used for multithreaded server hosts that can run multiple instances 
of the same script. The scripting engine may return ENOTIMPL, in which case 
the host can achieve the same result by duplicating the persistent state and 
creating a new instance of the scripting engine with IPersist*. 

5 

This method can be called from non-base threads without resulting in a non-base 
callout to host objects or to lActiveScriptSite. 



Returns 




S_OK 


The scripting engine was successfully cloned. 


E NOTIMPL 


The Clone method is not supported. 


E POINTER 


An invalid pointer was specified. 


E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized). 


See also IActiveScript::SetScriptSite, lActiveScriptSite, 



IActiveScriptSite::Getltemlnfo 



lActiveScript:: Close 

HRESULT Close (void); 

15 

Causes the scripting engine to abandon any currently loaded script, lose its state, 
and release any interface pointers it has to other objects, thus entering a closed 
state. Event sinks, immediately executed script text, and macro invocations that 
are already in progress are completed before the state changes (use 
20 InterruptScriptThread to cancel a running script thread). This method must be 
called by the creating host before it calls Release to prevent circular reference 
problems. 



Returns 




S OK 


The script was successfully closed. 


S FALSE 


The method succeeded, but the script was 




already closed. 
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OLESCRIPT S PENDING 


The method was queued successfully, but the 




state hasrTt changed yet. When the state 


changes, the site will be called back on 
IActiveScriptSite::OnStateChange. 


E UNEXPECTED 


The call was not expected (for example, the 




scripting engine was already in the closed state). 



See also IActiveScript::lnterruptScriptThread, IActiveScriptSite::OnStateChange 



IActiveScript::GetCurrentScriptThreadlD 

5 HRESULT GetCurrentScriptThreadID ( 

SCRIPTTHREADID *pstidThread // receives scripting thread identifier 

li 

Retrieves a scripting-engine-defined identifier for the currently executing thread. 
10 The identifier can be used in subsequent calls to script thread execution-control 
methods such as InterruptScriptThread. 

pstidThread 

[out] Address of a variable that receives the script thread identifier associated 
15 with the current thread. The interpretation of this identifier is left to the scripting 
engine, but it can be just a copy of the Windows thread identifier. If the Win32 
thread terminates, this identifier becomes unassigned and can subsequently be 
assigned to another thread. 

20 This method can be called from non-base threads without resulting in a non-base 
callout to host objects or to lActiveScriptSite. 



Returns 




S OK 


The identifier was successfully retrieved. 


E POINTER 


An invalid pointer was specified. 



See also IActiveScript::lnterruptScriptThread, lActiveScriptSite 

25 

29 



1001/047 

IActiveScript::GetScriptDispatch 

HRESULT GetScriptDispatch ( 

LPCOLESTR pstrltemName // address of item name 
IDispatch **ppdisp // receives IDispatch pointer 

5 ii 

Retrieves the IDispatch interface for the methods and properties associated with 
the running script itself. 

10 pstrltemName 

[in] Address of a buffer that contains the name of the item for which the caller 
needs the associated dispatch object. If this parameter is NULL, the dispatch 
object contains as its members all of the global methods and properties 
defined by the script. Through the IDispatch interface and the associated 

15 ITypelnfo interface, the host can invoke script methods or view and modify 
script variables. 
ppdisp 

[out] Address of a variable that receives a pointer to the object associated with 
the script's global methods and properties. If the scripting engine does not 
20 support such an object, NULL is returned. 

Because methods and properties can be added by calling lActiveScriptParse, the 
IDispatch interface returned by this function can dynamically support new 
methods and properties. Similarly, IDispatch: :GetTypelnfo should return a new, 
25 unique ITypelnfo when methods and properties are added. Note, however, that 
language engines must not change the IDispatch interface in a way that is 
incompatible with any previous ITypelnfo interface returned. That implies, for 
example, that DISPIDs will never be reused. 



Returns 




S OK 


The dispatch object for the script was successfully 




retrieved. 


S FALSE 


The scripting engine does not support a dispatch object; 




the pptf/spparameter is set to NULL. 
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E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized). 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 



lActiveScript: :GetScriptSite 

* HRESULT GetScriptSite ( 

REFIID iid, // interface identifier 

5 void **ppvSiteObject // address of host site interface 

n 

Retrieves the site object associated with the ActiveX Scripting engine. 
10 iid 

[in] Identifier of the requested interface. 
ppvSiteObject 

[out] Address of the location that receives the interface pointer to the host's 
site object. 

15 



Returns 




S OK 


The site object was successfully retrieved. 


S FALSE 


No site has been set; ppvSiteObject is set to NULL. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 


E NOINTERFACE 


The specified interface is not supported. 



I Acti veScri pt : : GetScri ptState 

HRESULT GetScriptState ( 

SCRI PTSTATE *pss // address of structure for state information 

20 }_; 

Retrieves the current state of the scripting engine. This method can be called 
from non-base threads without resulting in a non-base callout to host objects or to 
lActiveScriptSite. 
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pss 

[out] Address of a variable that receives a value defined in the SCRIPTSTATE 
enumeration. The value indicates the current state of the scripting engine 
5 associated with the calling thread. 



Returns 




S OK 


The state information was successfully retrieved. 


E POINTER 


An invalid pointer was specified. 



See also lActiveScriptSite, SCRIPTSTATE 



10 lActiveScript::GetScriptThreadlD 

HRESULT GetScriptThreadID ( 

DWORD dwWin32ThreadlD, // Win32 thread identifier 
SCRIPTTHREADID *pstidThread // receives scripting thread identifier 

li 

15 

Retrieves a scripting-engine-defined identifier for the thread associated with the 
given Win32 thread. This identifier can be used in subsequent calls to script 
thread execution control methods such as InterruptScriptThread. 

20 dwWin32ThreadlD 

[in] Thread identifier of a running Win32 thread in the current process. Use 
the GetCurrentScriptThreadID function to retrieve the thread identifier of the 
currently executing thread. 
pstidThread 

25 [out] Address of a variable that receives the script thread identifier associated 

with the given Win32 thread. The interpretation of this identifier is left to the 
scripting engine, but it can be just a copy of the Windows thread identifier- 
Note that if the Win32 thread terminates, this identifier becomes unassigned 
and may subsequently be assigned to another thread. 

30 
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This method can be called from non-base threads without resulting in a non-base 
callout to host objects or to lActiveScriptSite. 



Returns 




S OK 


The identifier was successfully retrieved. 


E POINTER 


An invalid pointer was specified. 


E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized). 



5 See also IActiveScript::lnterruptScriptThread, lActiveScriptSite 



I Acti veScri pt : : GetScri ptTh read State 

HRESULT GetScriptThreadState ( 

SCRIPTTHREADID stidThread, // identifier of script thread 

10 SCRIPTTHREADSTATE *pstsState // receives state flag 

11 

Retrieves the current state of a script thread. 
15 stidThread 

[in] Identifier of the thread for which the state is desired, or one of the following 
special thread identifiers: 

Value Meaning 

SCRIPTTHREADID_CURRENT The currently executing thread. 
20 SCRIPTTHREADID_BASE The base thread; that is, the thread in which 

the scripting engine was instantiated. 

pstsState 

[out] Address of a variable that receives the state of the indicated thread. The 
state is indicated by one of the named constant values defined by the 
25 SCRIPTTHREADSTATE enumeration. If this parameter does not identify the 
current thread, the state may change at any time. 

This method can be called from non-base threads without resulting in a non-base 
callout to host objects or to lActiveScriptSite. 
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Returns 




S OK 


The current state was successfully retrieved. 


E POINTER 


An invalid pointer was specified. 


E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized). 



See also lActiveScriptSite, SCRI PTTH RE ADSTATE 



5 IActiveScript::lnterruptScriptThread 

HRESULT InterruptScriptThread ( 

SCRIPTTHREADID stidThread, // identifier of thread 

const EXCEPINFO *pexcepinfo, // receives error information 

DWORD dwFlags 

10 l: 

Interrupts the execution of a running script thread (an event sink, an immediate 
execution, or a macro invocation). This method can be used to terminate a script 
that is stuck (for example, in an infinite loop). It can be called from non-base 
15 threads without resulting in a non-base callout to host objects or to 
lActiveScriptSite. 

stidThread 

[in] Thread identifier of the thread to interrupt, or one of the following special 
20 thread 

identifier values: 



Value 


Meaning 


SCRIPTTHREADID CURRENT 


The currently executing thread. 


SCRIPTTHREADID BASE 


The base thread; that is, the thread in which 




the scripting engine was instantiated. 


SCRIPTTHREADID ALL 


All threads. The interrupt is applied to all 
script methods currently in progress. Note 


that unless the caller has requested that the 


script be disconnected, by calling 
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SetScriptState with the 




SCRIPTSTATE DISCONNECTED or 




SCRIPTSTATE INITIALIZED flag, the next 




scripted event causes script code to run 




again. 



pexcepinfo 

[in] Address of an EXCEPINFO structure that receives error information 
associated with the error condition. 
5 dwFlags 

[in] Option flags associated with the interruption. Can be one of these values: 

SCRIPTINTERRUPT_DEBUG 

If supported, enter the scripting engine's debugger at the current script 

execution point. 
10 SCRIPTINTERRUPTJRAISEEXCEPTION 

If supported by the scripting engine's language, let the script handle the 
exception. Otherwise, the script method is aborted and the error code is returned 
to the caller; that is, the event source or macro invoker. 



Returns 




S OK 


The given thread was successfully interrupted. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 


E UNEXPECTED 


The call was not expected (for example, the scripting 




engine has not yet been loaded or initialized). 



15 

See also IActiveScript::SetScriptState, lActiveScriptSite 

IActiveScript::SetScriptSite 

HRESULT SetScriptSite ( 
20 lActiveScriptSite *pScriptSite // address of host script site 

h 

Informs the scripting engine of the lActiveScriptSite site provided by the host. 
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This method must be called before any other lActiveScript methods can be used. 
p Script Site 

[in] Address of the host-supplied script site to be associated with this instance 
5 of the scripting engine. The site must be uniquely assigned to this scripting 
engine instance; cannot be shared with other scripting engines. 



Returns 




S_OK 


The host site was set successfully. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 


E FAIL 


An unspecified error occurred; the scripting engine was 




unable to finish initializing the site. 


E UNEXPECTED 


The call was not expected (for example, a site was 




already set). 



See also lActiveScriptSite 

10 

lActiveScript: :SetScriptState 

HRESULT SetScriptState ( 

SCRIPTSTATE ss // identifier of new state 

1: 

15 

Puts the scripting engine into the given state. This method can be called from 
non-base threads without resulting in a non-base callout to host objects or to 
lActiveScriptSite. 

20 ss 

[in] Sets the scripting engine to the given state. Can be one of the values 
defined in the SCRIPTSTATE enumeration: 

SCRIPTSTATEJNITIALIZED 

25 Returns the scripting engine back to the initialized state from the started, 

connected, or disconnected state. Because languages can vary widely in 
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semantics, scripting engines are not required to support this state 
transition. Engines that support IActiveScript::Clone must, however, 
support this state transition. Hosts must prepare for this transition and take 
the appropriate action: Release the current scripting engine, create a new 
scripting engine, and call Load or InitNew (and possibly also call 
ParseScriptText). Use of this transition should be considered an 
optimization of the above steps. Note that any information the scripting 
engine has obtained about the names of Named Items and the type 
information describing Named Items remains valid. 

Because languages vary widely, defining the exact semantics of this 
transition is difficult. At a minimum, the scripting engine must disconnect 
from all events, and release all of the SCRIPTINFOJUNKNOWN pointers 
obtained by calling IActiveScriptSite::Getltemlnfo. The engine must refetch 
these pointers after the script is run again. The scripting engine should 
also reset the script back to an initial state that is appropriate for the 
language. VBScript, for example, resets all variables and retains any code 
added dynamically by calling lActiveScriptParse with the 
SCRIPTTEXTJSPERSISTENT flag set. Other languages may need to 
retain current values (such as Lisp because there is no code/data 
separation) or reset to a well-known state (this includes languages with 
statically initialized variables). These languages may or may not retain 
code added by calling lActiveScriptParse. 

Note that the transition to the started state should have the same 
semantics (that is, it should leave the scripting engine in the same state) as 
calling IPersist*::Save to save the scripting engine, and then calling 
lPersist*::Load to load a new scripting engine; these actions should have 
the same semantics as lActiveScript:: Clone. Scripting engines that do not 
yet support Clone or IPersist* should carefully consider how the transition 
to the started state should behave, so that such a transition would not 
violate the above conditions if Clone or IPersist* support was later added. 
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During this transition to the started state, the scripting engine will 
disconnect from event sinks after the appropriate destructors, and so on, 
are executed in the script. To avoid having these destructors executed, the 
host can first move the script into the disconnected state before moving into 
5 the started state. 

Use InterruptScriptThread to cancel a running script thread without waiting 
for current events, and so on, to finish running. 

10 SCRIPTSTATE_STARTED 

The transition to this mode causes any code that was queued during the 
initialized state to be executed. From this state, script code can be 
executed, for example, by calling IActiveScriptParse::ParseScriptText or by 
calling the IDispatch interface obtained from 
15 IActiveScript::GetScriptDispatch. The transition to this state is also the 

appropriate time to execute routines such as a main()-like script routine, if 
appropriate for the script language. 

SCRIPTSTATE_CONNECTED 

20 Causes the script to connect to events. If this is a transition from the 

initialized state, the scripting engine should transition through the started 
state, performing the necessary actions, before entering the connected 
state and connecting to events. 

25 SCRIPTSTATE_DISCONNECTED 

Causes the script to disconnect from event sinks. This can be done either 
logically (ignoring events received) or physically (calling Unadvise on the 
appropriate connection points). Returning to the connected state reverses 
this process. If this is a transition from the initialized state, the scripting 
30 engine should transition through the started state, performing the 

necessary actions, before entering the disconnected state. Event sinks 
that are in progress are completed before the state changes (use 
InterruptScriptThread to cancel a running script thread). The script's 
execution state is maintained. For example, an HTML browser may put the 
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scripting engine into this state when a scripted HTML page is moved into 
the LRU cache, before the page is actually destroyed. 



Returns 




S OK 


The script successfully entered the given state. 


S FALSE 


The method succeeded, but the script was 




already in the given state. 


OLESCRIPT S PENDING 


The method was queued successfully, but the 




state hasn't changed yet. When the state 


changes, the site will be called back through the 


IActiveScriptSite::OnStateChange method. 


E FAIL 


The scripting engine does not support the 




transition back to the initializedstate. The host 


must discard this scripting engine and create, 


initialize, and load a new scripting engine to 


achieve the same effect. 


E UNEXPECTED 


The call was not expected (for example, the 




scripting engine has not yet been loaded or 


initialized). 



5 See also IActiveScript::Clone, IActiveScript::GetScriptDispatch, 

IActiveScript::lnterruptScriptThread, IActiveScriptParse::ParseScriptText, 
lActiveScriptSite, 

IActiveScriptSite::Getltemlnfo, IActiveScriptSite::OnStateChange, SCRIPTSTATE 



10 lActiveScriptParse 

If the ActiveX Scripting engine allows raw text code scriptlets to be added to the 
script, or allows expression text to be evaluated at run time, it implements 
lActiveScriptParse. For interpreted scriptjng languages that have no 
independent authoring environment, such as Visual Basic Script, this provides an 
15 alternate mechanism (other than IPersist*) to get script code into the scripting 
engine, and to attach script fragments to various object events. 

Methods in Vtable Order 
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lUnknown methods 


Description 


Querylnterface 


Returns pointers to supported interfaces. 


AddRef 


Increments the reference count. 


Release 


Decrements the reference count. 


lActiveScriptParse Methods 


Description 


In it New 


Initializes the scripting engine. 


AddScriptlet 


Adds a code scriptlet to the script. 


ParseScriptText 


Parses the given code scriptlet, adding 
declarations into the name space and 
evaluating code as appropriate. 


lActiveScriptParse: :AddScriptlet 

HRESULT AddScriptlet ( 

LPCOLESTR pstrDefaultName, // address of default name of 


scriptlet 

LPCOLESTR pstrCode, 


// address of scriptlet text 



10 



LPCOLESTR pstrltemName, 


// 


address of item name 


LPCOLESTR pstrSubltemName, 




// address of subitem name 


LPCOLESTR pstrEventName, 


// 


address of event name 


LPCOLESTR pstrEnd Delimiter 




// address of end-of-scriptlet 


delimiter 






DWORD dwFlags, 


// 


scriptlet flags 


BSTR *pbstrName, 


// 


address of actual name of scriptlet 


EXCEPINFO *pexcepinfo 


// 


address of exception information 



15 h 

Adds a code scriptlet to the script. This method is used in environments where 
the persistent state of the script is intertwined with the host document and must be 
restored under the host's control, rather than through IPersist*. The primary 
20 examples are HTML scripting languages that allow scriptlets of code embedded in 
the HTML document to be attached to intrinsic events (for example, 
ONCLICK^'buttonl.text^Exit"') 

pstrDefaultName 
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[in] Address of a default name to associate with the scriptlet. If the scriptlet 
does not contain naming information (as in the ONCLICK example above), 
this name will be used to identify the scriptlet. If this parameter is NULL, the 
scripting engine manufactures a unique name, if necessary. 
5 pstrCode 

[in] Address of the scriptlet text to add. The interpretation of this string 
depends on the scripting language. 
pstrltemName 

[in] Address of a buffer that contains the item name associated with this 
10 scriptlet. This parameter, in addition to pstrSubltemName, identifies the 

object for which the scriptlet is an event handler. 
pstrSubltemName 

[in] Address of a buffer that contains the name of a subobject of the named 
item with which this scriptlet is associated; this name must be found in the 
15 named item's type information. This parameter is NULL if the scriptlet is to be 

associated with the named item instead of a subitem. This parameter, in 
addition to pstrltemName, identifies the specific object for which the scriptlet 
is an event handler. 
pstrE vent Name 

20 [in] Address of a buffer that contains the name of the event for which the 

scriptlet is an event handler. 
pstrEndDelimiter 

[in] Address of the end-of-scriptlet delimiter. When pstrCode is parsed from a 
stream of text, the host typically uses a delimiter, such as two single quotation 

25 marks ("), to detect the end of the scriptlet. This parameter specifies the 

delimiter that the host used, allowing the scripting engine to provide some 
conditional primitive preprocessing (for example, replacing a single quotation 
mark ['] with two single quotation marks for use as a delimiter). Exactly how 
(and if) the scripting engine makes use of this information depends on the 

30 scripting engine. Set this parameter to NULL if the host did not use a 

delimiter to mark the end of the scriptlet. 
dwFlags 

[in] Flags associated with the scriptlet. Can be a combination of the following 
values: 
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Value 


Meaning 


SCRIPTTEXT ISVISIBLE 


Indicates that the script text should be visible 




(and, therefore, callable by name) as a global 


method in the name space of the script. 


SCRIPTTEXT ISPERSISTENT 


Indicates that the code added during this call 




should be saved if the scripting engine is 

i / ^ iii i iim 

saved (for example, through a call to 
IPersist*::Save), or if the scripting engine is 


reset by way of a transition back to the 
initialized state. 



pbstrName 

[out] The actual name used to identify the scriptlet. This will be, in order of 
preference: a name explicitly specified in the scriptlet text, the default name 
5 provided in pstrDefaultName, or a unique name synthesized by the scripting ' 

engine. 
pexcepinfo 

[out] Pointer to a structure containing exception information. This structure 
should be filled in if DISP E EXCEPTION is returned. 



Returns 




S OK 


The scriptlet was successfully added to the 




script—the pbstrName parameter contains 


the scriptlet's name. 


OLESCRIPT E INVALIDNAME 


The default name supplied is invalid in this 




scripting language. 


OLESCRIPT E SYNTAX 


An unspecified syntax error occurred in the 




scriptlet. 


DISP E EXCEPTION 


An exception occurred in the parsing of the 




scriptlet; the pexcepinfo parameter contains 


information about the exception. 


E UNEXPECTED 


The call was not expected (for example, the 




scripting engine has not yet been loaded or 
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initialized). 


E NOTIMPL 


This method is not supported; the scripting 




engine does not support adding event- 
sinking scriptlets. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 



IActiveScriptParse::lnitNew 

HRESULT InitNew (void); 



5 Initializes the scripting engine. 

Before the scripting engine can be used, one of the following methods must be 
called: IPersist*::Load, IPersist*::lnitNew, or I ActiveScriptParse:: InitNew. The 
semantics of this method are identical to IPersistStreamlnit::lnitNew, in that this 
10 method tells the scripting engine to initialize itself. Note that it is not valid to call 
both InitNew and Load, nor is it valid to call InitNew or Load more than once. 



Returns 




S_OK 


The scripting engine was successfully initialized. 






E FAIL 


An error occurred during initialization. 


I Acti veScri ptPa rse : : 


ParseScriptText 



15 HRESULT ParseScriptText ( 

LPCOLESTR pstrCode, // address of scriptlet text 

LPCOLESTR pstrltemName, // address of item name 

I Unknown *punkContext, // address of debugging context 

LPCOLESTR pstrEnd Delimiter, // address of end-of-scriptlet delimiter 

20 DWORD dwFlags, // scriptlet flags 

VARIANT *pvarResult, // address of buffer for results 

EXCEPINFO *pexcepinfo // address of buffer for error data 

1; 
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Parses the given code scriptlet, adding declarations into the name space and 



evaluating code as appropriate. 



pstrCode 

5 [in] Address of the scriptlet text to evaluate. The interpretation of this string 

depends on the scripting language. 
pstrltemName 

[in] Address of the item name that gives the context in which the scriptlet is to 
be evaluated. If this parameter is NULL, the code is evaluated in the scripting 
10 engine's global context. 

punkContext 

[in] Address of context object. This object is reserved for use in a debugging 
environment, where such a context may be provided by the debugger to 
represent an active run-time context. If this parameter is NULL, the engine 
15 uses pstrltemName to identify the context. 

pstrEndDelimiter 

[in] Address of the end-of-scriptlet delimiter. When pstrCode is parsed from a 
stream of text, the host typically uses a delimiter, such as two single quotation 
marks ("), to detect the end of the scriptlet. This parameter specifies the 

20 delimiter that the host used, allowing the scripting engine to provide some 

conditional primitive preprocessing (for example, replacing a single quotation 
mark ['] with two single quotation marks for use as a delimiter). Exactly how 
(and if) the scripting engine makes use of this information depends on the 
scripting engine. Set this parameter to NULL if the host did not use a 

25 delimiter to mark the end of the scriptlet. 



dwFlags 

[in] Flags associated with the scriptlet. Can be a combination of these values: 



Value 


Meaning 


SCRIPTTEXT ISEXPRESSION 


If the distinction between a computational 




expression and a statement is important but 


syntactically ambiguous in the script 
language, this flag specifies that the scriptlet 


is to be interpreted as an expression, rather 


than as a statement or list of statements. By 
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default, statements are assumed unless the 


correct choice can be determined from the 


syntax of the scriptlet text. 


SCRIPTTEXT ISPERSISTENT 


Indicates that the code added during this call 




should be saved if the scripting engine is 
saved (for example, through a call to 
IPersist*::Save), or if the scripting engine is 


reset by way of a transition back to the 
initialized state. 


SCRIPTTEXT ISVISIBLE 


Indicates that the script text should be visible 




(and, therefore, callable by name) as a 
global method in the name space of the 


script. 



pvarResult 

[out] Address of a buffer that receives the results of scriptlet processing, or 
NULL if the caller expects no result (that is, the 
5 SCRIPTTEXTJSEXPRESSION value is not set). 

pexcepinfo 

[out] Address of a structure that receives exception information. This 
structure is filled if ParseScriptText returns DISP_E_EXCEPTION. 

10 If the scripting engine is in the initialized state, no code will actually be evaluated 
during this call; rather, such code is queued and executed when the scripting 
engine is transitioned into (or through) the started state. Because execution is not 
allowed in the initialized state, it is an error to call this method with the 
SCRIPTTEXTJSEXPRESSION flag when in the initialized state. 

15 

The scriptlet can be an expression, a list of statements, or anything allowed by the 
script language. For example, this method is used in the evaluation of the HTML 
<SCRIPT> tag, which allows statements to be executed as the HTML page is 
being constructed, rather than just compiling them into the script state. 
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The code passed to this method must be a valid, complete portion of code. For 
example, in VBScript it is illegal to call this method once with Sub Foo(x) and then 
a second time with End Sub. The parser must not wait for the second call to 
complete the subroutine, but rather must generate a parse error because a 
subroutine declaration was started but not completed. 



Returns 




S OK 


The expression or statement(s) has been 
evaluated. The pvarResult parameter contains the 


result, if any. 


E_POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 


E UNEXPECTED 


The call was not expected (for example, the 




scripting engine is in the uninitialized or closed 


state, or the SCRIPTTEXTJSEXPRESSION flag 


was set and the scripting engine is in the initialized 


state). 


DISP E EXCEPTION 


An exception occurred in the processing of the 




scriptlet. The pexcepinfo parameter contains 


information about the exception. 


OLESCRIPT E SYNTAX 


An unspecified syntax error occurred in the 




scriptlet. 


E NOTIMPL 


This method is not supported. The scripting engine 




does not support run-time evaluation of 
expressions or statements. 



10 



lActiveScriptError 

An object implementing this interface is passed to IActiveScriptSite::OnScriptError 
whenever the scripting engine encounters an unhandled error. The host then 
calls methods on this object to obtain information about the error that occurred. 



Methods in Vtable Order 



lllnknown methods 



Description 
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Querylnterface 


Returns pointers to supported interfaces. 


AddRef 


Increments the reference count. 


lActiveScriptError methods 


Description 


GetExceptionlnfo 


Retrieves information about an error. 


GetSourcePosition 


Retrieves the location in the source code where 




an error occurred. 


GetSourceLineText 


Retrieves the line in the source file where an 




error occurred. 


lActiveScriptError: :GetExceptionlnfo 


HRESULT GetExceptionlnfo ( 
EXCEPINFO *pexcepinfo 


// structure for exception information 


11 

Retrieves information about an error that occurred while the scripting engine was 



running a script. 
10 pexcepinfo 

[out] Address of an EXCEPINFO structure that receives error information. 



Returns 




S OK 


The error information was successfully retrieved. 


E FAIL 


An error occurred. 



IActiveScriptError::GetSourceLineText 

15 HRESULT GetSourceLineText ( 

BSTR *pbstrSourceLine // address of buffer for source line 

Retrieves the line in the source file where an error occurred while a scripting 
20 engine was running a script. 

pbstrSourceLine 
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[out] Address of a buffer that receives the line of source code in which the 
error occurred. 



Returns 




S OK 


The line in the source file was successfully retrieved. 


E FAIL 


An error occurred. 



5 IActiveScriptError::GetSourcePosition 

HRESULT GetSourcePosition ( 

DWORD *pdwSourceContext, IJ_ context cookie 

ULONG *pulLineNumber, // line number of error 
LONG *pichCharPosition // character position of error 

10 ]_; 

Retrieves the location in the source code where an error occurred while the 
scripting engine was running a script. 

15 pdwSourceContext 

[out] Address of a variable that receives a cookie that identifies the context. 
The interpretation of this parameter depends on the host application. 
pulLineNumber 

[out] Address of a variable that receives the line number in the source file 
20 where the error occurred. 
pichCharPosition 

[out] Address of a variable that receives the character position in the line 
where the error occurred. 



Returns 




S OK 


The error location was successfully retrieved. 


E FAIL 


An error occurred. 



25 

lActiveScriptSite 
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The host must create a site for the ActiveX Scripting engine by implementing 
lActiveScriptSite. Usually, this site will be associated with the container of all the 
objects that are visible to the script (for example, the ActiveX controls). Typically, 
this container will correspond to the document or page being viewed. Internet 
5 Explorer, for example, would create such a container for each HTML page being 
displayed. Each ActiveX control (or other automation object) on the page, and the 
scripting engine itself, would be enumerable within this container. 



Methods in Vtable Order 



lUnknown methods 


Description 


Query interface 


Returns pointers to supported interfaces. 


AddRef 


Increments the reference count. 


Release 


Decrements the reference count. 


lActiveScriptSite methods 


Description 


GetLCID 


Retrieves the locale identifier that the host uses 




for displaying user-interface elements. 


Getltemlnfo 


Obtains information about an item that was 




added to an engine through a call to the 
IActiveScript::AddNamedltem method. 


GetDocVersionStnng 


m ^ | • lit It* l 1 i ■ ft 

Retrieves a host-defined string that uniquely 




identifies the current document version from the 


host's point of view. 


OnScriptTerminate 


Informs the host that the script has completed 




execution. 


OnStateChange 


Informs the host that the scripting engine has 




changed states. 


OnScriptError 


Informs the host that an execution error occurred 




while the engine was running the script. 


OnEnterScript 


Informs the host that the scripting engine has 




begun executing the script code. 


OnLeaveScript 


Informs the host that the scripting engine has 




returned from executing script code. 



10 

lActiveScriptSite: :GetDocVersionString 
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HRESULT GetDocVersionString ( 

BSTR *pbstrVersionString // address of document version string 

11 

5 Retrieves a host-defined string that uniquely identifies the current document 
version from the host's point of view. If the related document has changed 
outside the scope of ActiveX Scripting (as in the case of an HTML page being 
edited with NotePad), the scripting engine can save this along with its persisted 
state, forcing a recompile the next time the script is loaded. 

10 

pstrVersionString 

[out] Address of the host-defined document version string. 



Returns 




S OK 


The document version string was successfully retrieved. The 




pstrVersionString parameter contains the string. 


E NOTIMPL 


This method is not supported. The scripting engine should 




assume that the script is in sync with the document. 



15 IActiveScriptSite::Getltemlnfo 

HRESULT IActiveScriptSite::Getltemlnfo ( 

LPCOLESTR pstrName, // address of item name 

DWORD dwReturnMask, // bit mask for information retrieval 

lUnknown **ppunkltem, // address of pointer to item's I Unknown 
20 ITypelnfo **ppTypelnfo // address of pointer to item's ITypelnfo 

n 

Allows the scripting engine to obtain information about an item added with 
IActiveScript::AddNamedltem. 

25 

pstrName 

[in] The name associated with the item, as specified in 
IActiveScript::AddNamedltem. 
dwReturnMask 
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[in] A bit mask specifying what information about the item should be returned. 
The scripting engine should request the minimum needed information 
because some of the return parameters (for example, ITypelnfo) can take 
considerable time to load or generate. Can be a combination of the following 
5 values: 



Value 


Meaning 


SCRIPTINFO IUNKNOWN 


Return the lUnknown interface for this item. 


SCRIPTINFO ITYPEINFO 


Return the ITypelnfo interface for this item. 







ppunkitem 

[out] Address of a variable that receives a pointer to the lUnknown interface 
associated with the given item. The scripting engine can use the 

10 Querylnterface method to obtain the IDispatch interface for the item. This 

parameter receives NULL if dwReturnMask does not include the 
SCRIPTINFOJUNKNOWN value. Also, it receives NULL if there is no object 
associated with the item name; this mechanism is used to create a simple 
class when the named item was added with the SCRIPTITEM CODEONLY 

15 flea set. 

ppTypelnfo 

[out] Address of a variable that receives a pointer to the ITypelnfo interface 
associated with the item. This parameter receives NULL if dwReturnMask 
does not include the SCRIPTINFOJTYPEINFO value, or if type information is 

20 not available for this item. If type information is not available, the object 

cannot source events, and name binding must be realized with 
IDispatch::GetlDsOfNames. Note that this ITypelnfo describes the coclass 
(TKIND_COCLASS) because the object may support multiple interfaces and 
event interfaces. If the item supports the IProvideMultipleTypelnfo 

25 interface, the ITypelnfo interface corresponds to the ITypelnfo of index zero 

obtained from IProvideMultipleTypelnfo: :GetinfoOflndex. 

This method retrieves only the information indicated by the dwReturnMask 
parameter. This improves performance, for example, in the case where an 
30 ITypelnfo interface is not needed for an item. 
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Returns 




S OK 


The requested interface pointer was 
successfully retrieved. The ppunkltem or 


—w— ix x x • xi_ * x 

ppTypelnfo parameter contains the pointer. 


E POINTER 


An invalid pointer was specified. 


E INVALIDARG 


An argument was invalid. 


TYPE E ELEMENTNOTFOUND 


An item of the specified name was not 




found. 



See also IActiveScript::Add Named Item 



5 IActiveScriptSite::GetLCIP 

HRESULT GetLCID ( 

LCID *plcid // address of variable for language identifier 

11 

10 Retrieves the locale identifier associated with the host's user interface. The 
scripting engine uses the identifier to ensure that error strings and other user- 
interface elements surfaced by the engine appear in the appropriate language. If 
this method returns E_NOTIMPL, the system-defined locale identifier should be 
used. 

15 

plcid 

[out] Address of a variable that receives the locale identifier for user-interface 
elements displayed by the scripting engine. 



Returns 




S OK 


The locale identifier was successfully retrieved. The plcid 




parameter contains the identifier. 


E POINTER 


An invalid pointer was specified. 


E NOTIMPL 


This method is not implemented. Use the system-defined 




locale. 



20 
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IActiveScriptSite::OnEnterScript 



HRESULT OnEnterScript (void); 



Informs the host that the scripting engine has begun executing the script code. 

5 

The scripting engine must call this method on every entry or reentry into the 
scripting engine. For example, if the script calls an object that then fires an event 
handled by the scripting engine, the scripting engine must call OnEnterScript 
before executing the event, and must call OnLeaveScript after executing the event 
10 but before returning to the object that fired the event. Calls to this method can be 
nested. Every call to OnEnterScript requires a corresponding call to 
OnLeaveScript. 



Returns 




S OK 


The method succeeded. 



15 See also IActiveScriptSite::OnLeaveScript 

IActiveScriptSite::OnLeaveScript 

HRESULT IActiveScriptSite::OnLeaveScript (void); 

20 Informs the host that the scripting engine has returned from executing script code. 

The scripting engine must call this method before returning control to a caller that 
entered the scripting engine. For example, if the script calls an object that then 
fires an event handled by the scripting engine, the scripting engine must call 
25 OnEnterScript before executing the event, and must call OnLeaveScript after 

executing the event before returning to the object that fired the event. Calls to this 
method can be nested. Every call to OnEnterScript requires a corresponding call 
to OnLeaveScript. 



Returns 




S OK 


The method was successful. 



30 
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See also IActiveScriptSite::OnEnterScript 

IActiveScriptSite::OnScriptError 

HRESULT IActiveScriptSite::OnScriptError ( 
5 IActiveScriptError*pase // address of error interface 

1; 

Informs the host that an execution error occurred while the engine was running 
the script. 

10 

pase 

[in] Address of the error object's lActiveScriptError interface. A host can use 
this interface to obtain information about the execution error. 
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Returns 




S OK 


The scripting engine should continue running the script as best 




as possible (perhaps abandoning the processing of this event). 


S FALSE 


The scripting engine should continue running the script in the 




debugger, if a debugger is available. If a debugger is not 


available, this error should be handled in the same way as 


E FAIL. 


E FAIL 


The scripting engine should abort execution of the script and 




return it to the initialized state. In this case, the pexcepinfo 


parameter obtained from IActiveScriptError::GetExceptionlnfo 


is generally passed to OnScriptTerminate. 



See also lActiveScriptError, IActiveScriptError::GetExceptionlnfo 



5 IActiveScriptSite::OnScriptTerminate 

HRESULT OnScriptTerminate ( 

VARIANT *pvarResult, // address of script results 

EXCEPINFO *pexcepinfo // address of structure with exception information 

1; 

10 

Informs the host that the script has completed execution. 
pvarResult 

[in] Address of a variable that contains the script result, or NULL if the script 
15 produced no result. 
pexcepinfo 

[in] Address of an EXCEPINFO structure that contains exception information 
generated when the script terminated, or NULL if no exception was 
generated. 

20 

The scripting engine calls this method before the call to 
OnStateChange(SCRIPTSTATE INITIALIZED) is completed. The 
OnScriptTerminate method can be used to return completion status and results 



i 
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to the host. Note that many script languages, which are based on sinking events 
from the host, have life spans that are defined by the host. In this case, this 
method may never be called. 



Returns 




S OK 


The method succeeded. 



5 

IActiveScriptSite::OnStateChange 

HRESULT IActiveScriptSite::OnStateChange ( 

SCRIPTSTATE ssScriptState // new state of engine 

ii 

10 

Informs the host that the scripting engine has changed states. 

ssScriptState 

[in] Value that indicates the new script state. See 
15 IActiveScript::GetScriptState for a description of the states. 



Returns 




S OK 


The method succeeded. 



See also IActiveScript::GetScriptState 

20 lActiveScriptSiteWindow 

This interface is implemented by hosts that support a user interface on the same 
object as lActiveScriptSite. Hosts that do not support a user interface, such as 
servers, would not implement the lActiveScriptSiteWindow interface. The 
scripting engine accesses this interface by calling Query Interface from 
25 lActiveScriptSite. 



Methods in Vtable Order 



lUnknown methods 


Description 


Querylnterface 


Returns pointers to supported interfaces. 


AddRef 


Increments the reference count. 
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Release 


Decrements the reference count. 


lActiveScriptSiteWindow methods 


Description 


GetWindow 


Retrieves the window handle that can 
act as the owner of a pop-up window 
that the scripting engine needs to 
display. 


EnableModeless 


Causes the host to enable or disable its 
main window as well as any modeless 
dialog boxes. 


lActiveScriptSite:: EnableModeless 



HRESULT IActiveScriptSite::EnableModeless ( 
BOOL fEnable // enable flag 

5 H 

Causes the host to enable or disable its main window as well as any modeless 
dialog boxes. 

10 fEnable 

[in] Flag that, if TRUE, enables the main window and modeless dialogs or, if 
FALSE, disables them. 

This method is identical to IOIelnPlaceFrame::EnableModeless. 

15 

Calls to this method can be nested. 



Returns 


< 


S OK 


The method was successful. 


E FAIL 


An error occurred. 



lActiveScriptSite ::GetWindow 

20 HRESULT GetWindow ( 

HWND *phwnd // address of variable for window handle 
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Retrieves the handle of a window that can act as the owner of a pop-up window 
that the scripting engine needs to display. 



5 phwnd 

[out] Address of a variable that receives the window handle. 
This method is similar to IOIeWindow::GetWindow. 



Returns 




S OK 


The window handle was successfully retrieved. 


E FAIL 


An error occurred. 



10 

Enumerations 

SCRIPTSTATE 

15 typedef enum tagSCRIPTSTATE { 

SCRIPTSTATE_UNINITIALIZED = 0, 
SCRI PTSTATE_I N ITI ALIZED = 5, 





SCRIPTSTATE 


STARTED = 1, 






SCRIPTSTATE 


CONNECTED = 2, 




20 


SCRIPTSTATE 


DISCONNECTED 


3, 




SCRIPTSTATE 


CLOSED = 4 





} SCRIPTSTATE; 



Contains named constant values that specify the state of a scripting engine. This 
25 enumeration is used by the IActiveScript::GetScriptState, 

IActiveScript::SetScriptState, and IActiveScriptSite::OnStateChange methods. 



Elements 



SCRIPTSTATE UNINITIALIZED 


The script has just been created, but has 




not yet been initialized using an IPersist* 


interface and IActiveScript::SetScriptSite. 
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SCRIPTSTATE INITIALIZED 


The script has been initialized, but is not 




running (connecting to other objects or 
sinking events) or executing any code. 


Code can be queried for execution by 
calling 

IActiveScriptParse::ParseScriptText. 


SCRIPTSTATE STARTED 


The script can execute code, but is not yet 




sinking the events of objects added by the 


IActiveScript::AddNamedltem method. 


SCRIPTSTATE CONNECTED 


The script is loaded and connected for 




sinking events. 


SCRIPTSTATE DISCONNECTED 


The script is loaded and has a run-time 




execution state, but is temporarily 
disconnected from sinking events. 


SCRIPTSTATE CLOSED 


The script has been closed. The scripting 




engine no longer works and returns errors 


for most methods. 



See also IActiveScript::GetScriptState, IActiveScript::SetScriptState, 
IActiveScriptSite::OnStateChange 



5 SCRIPTTHREADSTATE 

typedef enum tagSCRIPTTHREADSTATE { 

SCRIPTTHREADSTATE NOTINSCRIPT = 0, 

SCRIPTTHREADSTATE RUNNING = 1 

} SCRIPTTHREADSTATE; 

10 

Contains named constant values that specify the state of a thread in a scripting 
engine. This enumeration is used by the IActiveScript::GetScriptThreadState 
method. 

15 Elements 

SCRIPTTHREADSTATE NOTINSCRIPT 
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The specified thread is not currently servicing a scripted event, processing 
immediately executed script text, or running a script macro. 
SCRIPTTHREADSTATE_RUNNING 

The specified thread is actively servicing a scripted event, processing 
5 immediately executed script text, or running a script macro. 



See also IActiveScript::GetScriptThreadState 



10 Appendix B: Active Debugging Environment Interfaces 
Language Engine 

lactiveScriptDebug; // provides syntax coloring and code context enumeration 
lactiveScriptErrorDebug; // returns document contexts and stack frames for errors 
15 lActiveScriptSiteDebug; // host provided link from script engine to debugger 
lActiveScriptTextlnfo; // Language engine debugging abstractions 
IDebugCodeContext; // a virtual "instruction pointer" in a thread 
lEnumDebugCodeContexts; 

IPebugStackFrame; // logical stack frame on the stack of a thread 
20 IPebugExpressionContext; // a context in which expressions can be evaluated 
IPebugStackFrameSniffer; // enumerator for stack frames known by an engine 
IPebugExpressionContext; // context for expression evaluation 
IPebugExpression; // an asynchronously evaluated expression 
IPebugSyncOperation; 
25 IPebugAsyncOperation; 

IPebugAsyncOperationCallBack; 

IPebugExpressionCallBack; // status events for IPebugExpression evaluation 
progress 

lEnumPebugExpressionContexts; 
30 IProvideExpressionContexts; // Object browsing 
IPebugFormatter; 



Hosts 
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Smart-host Helper Interfaces 

IDebugDocumentHelper; // implemented by PPM 
IDebugDocumentHost; // implemented (optionally) by the host 

5 Full Smart-host Interfaces 

// implemented by host 

IDebugDocumentlnfo; // provides info on (possibily uninstantiated) doc 
IDebugDocumentProvider; // allows doc to be instantiated on demand 
IDebugDocument; // base document interface 
10 IDebugDocumentText; // provides access to source text of document 
IDebugDocumentTextEvents; // events fired when source text changes 
I DebugDocumentTextAuthor; 

IDebugDocumentContext; // represents a range within the document 
// implemented by PPM on behalf of the host 
15 IPebugApplicationNode; // represents the position of a doc in the hierarchy 

IPebugApplicationNodeEvents; // events fired by PPM when document hierarchy 
changes 

Debugger IDE 

20 The IPE is a fully language independent debugging Ul. It provides: 

- Pocument viewers/editors. 

- Breakpoint management. 

- Expression evaluation and watch windows. 

- Stack frame browsing. 
25 - Object/Class browsing. 

- Browsing the virtual application structure. 

// Pebugger implementation 

IPebugSessionProvider; // establishes a debug session for a running application. 
30 lApplicationPebugger; // primary interface exposed by a debugger IPE session 

Machine Debug Manager 
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The machine debug manager provides the hookup point between virtual 
applications and debuggers by maintaining and enumerating a list of active virtual 
applications. 

5 IMachineDebugManager; 

IMachineDebugManagerCookie; 
IMachineDebugManagerEvents; 
lEnumRemoteDebugApplications; 

10 Process Debug Manager 

The PPM does the following: 

- Synchronizes the debugging of multiple language engines. 

- Maintains a tree of debuggable documents 

- Merges stack frames. 

15 - Coordinates breakpoints and stepping across language engines. 

- Tracks threads. 

- Maintains a debugger thread for asynchronous processing. 

- Communicates with the machine debug manager and the debugger IPE. 

20 The following are the interfaces provided by the process debug manager 

IProcessPebugManager; // creates, adds and removes virtual applications, etc. . 
IRemotePebugApplication; // virtual application abstraction 
IPebugApplication; 

IRemotePebugApplicationThread; // virtual thread abstraction 
25 I PebugAppI icationThread ; 

lEnumRemotePebugApplicationThreads; 
IPebugThreadCall; // dispatches marshalled calls 

IPebugApplicationNode; // maintains a position for a document in the hierarchy 
lEnumPebugApplicationNodes; 
30 lEnumPebugStackFrames; // merged enumeration of stack frames from engines 

Structures and Enumerations 

BREAKPOINT STATE 
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// Indicates the state of a breakpoint 
typedef enum tagBREAKPOINT STATE { 

BREAKPOINT_DELETED = 0, // Breakpoint no longer exists but references exist 
BREAKPOINT_DISABLED = 1, // Breakpoint exists but is disabled 
5 BREAKPOINT_ENABLED = 211 Breakpoint exists and is enabled 
} BREAKPOINT_STATE; 

APPBREAKFLAGS 

//Application break flags indicate the current application debug state and thread 
10 typedef DWORD APPBREAKFLAGS; 
// DEBUGGER_BI_OCK 

// languages should break immediately with 
BREAKREASON DEBUGGER BLOCK 

const APPBREAKFLAGSAPPBREAKFLAG _DEBUGGER_BLOCK= 0x00000001; 
15 // DEBUGGER_HALT 

// languages should break immediately with BREAKREASON DEBUGGER_HALT 
const APPBREAKFLAGSAPPBREAKFLAG DEBUGGER, HALT= 0x00000002; 
. //STEP 

// languages should break immediately in the stepping thread with 

20 BREAKREASON, STEP 

const APPBREAKFLAGSAPPBREAKFLAG STEP= 0x00010000; 
// NESTED - the application is in nested execution on a breakpoint 
const APPBREAKFLAGSAPPBREAKFLAG NESTED= 0x00020000; 
// STEP TYPES - defines whether we are stepping at source, bytecode, or 

25 machine level- 
const APPBREAKFLAGSAPPBREAKFLAG STEPTYPE SOURCE= 
0x00000000; 

const APPBREAKFLAGSAPPBREAKFLAG STEPTYPE BYTECODE= 
0x00100000; 

30 const APPBREAKFLAGSAPPBREAKFLAG_STEPTYPE_MACHINE= 
0x00200000; 

const APPBREAKFLAGSAPPBREAKFLAG STE PTYPE M ASK= OxOOFOOOOO; 
// BREAKPOINT IN PROGRESS 

const APPBREAKFLAGSAPPBREAKFLAG IN BREAKPOINT= 0x80000000; 



63 



1001/047 



BREAKREASON 

// Indicates the cause of hitting a breakpoint 
typedef enum tagBREAKREASON{ 
5 BREAKREASON_STEP, // Caused by the stepping mode 

BREAKREASON BREAKPOINT, // Caused by an explicit breakpoint 
BREAKREASON DEBUGGER BLOCK, // Caused by another thread breaking 
BREAKREASON HOST INITIATED, // Caused by host requested break 
BREAKREASON_LANGUAGE_INITIATED, // Caused by a scripted break 
10 BREAKREASON DEBUGGER_HALT, // Caused by debugger IDE requested 
break 

BREAKREASON ERROR // Caused by an execution error 
} BREAKREASON; 

15 BREAKRESUME_ACTION 

// How to continue from a breakpoint 
typedef enum tagBREAKRESUME_ACTION{ 
BREAKRESUMEACTION_ABORT, // Abort the application 
BREAKRESUMEACTION CONTINUE, // Continue running 
20 BREAKRESUMEACTION STEP INTO, // Step into a procedure 
BREAKRESUMEACTION STEP OVER, // Step over a procedure 
BREAKRESUMEACTION STEP_OUT // Step out of the current procedure 
} BREAKRESUMEACTION; 

25 ERRORRESUME_ACTION 

// How to continue from a run time error. 
typedef enum tagERRORRESUMEACTION { 

ERRORRESUMEACTION ReexecuteErrorStatement, // re-execute the erroneous 
line 

30 ERRORRESUMEACTION_AbortCallAndReturnErrorToCaller, // let language 
engine handle the error 

ERRORRESUMEACTION SkipErrorStatement, // resume execution beyond the 
error 

} ERRORRESUMEACTION; 
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DOCUMENTNAMETYPE 

// The type of name desired for a document. 
typedef enum tagDOCUMENTNAMETYPE { 
5 DOCUMENTNAMETYPE APPNODE, // Get name as it appears in the app tree 
DOCUMENTNAMETYPE__TITLE, // Get name as it appears on the doc viewer title 
bar 

DOCUMENTNAMETYPE FILE TAIL, // Get filename without a path (for save 
as...) 

10 DOCUMENTNAMETYPE URL, // Get URL of the document, if any 
} DOCUMENTNAMETYPE; 

SOU RC E_TEXT_ATT R 

// Attributes of a single character of source text. 
15 typedef WORD SOURCE TEXT ATTR; 

// The character is a part of a language keyword. Example: while 

const SOURCE_TEXT_ATTR SOURCETEXT_ATTR_KEYWORD= 0x0001; 

// The character is a part of a comment block. 

const SOURCE_TEXT_ATTR SOURCETEXT_ATTR COMMENT= 0x0002; 

20 // The character is not part of compiled language source text. Example: 
// the HTML surrounding script blocks- 
const SOURCE_TEXT_ATTR SOURCETEXT_ATTR_NONSOURCE= 0x0004; 
// The character is a part of a language operator. Example: * 
const SOURCE_TEXT_ATTR SOURCETEXT_ATTR_OPERATOR= 0x0008; 

25 // The character is a part of a language numeric constant. Example: 1234 
const SOU RCE_TEXT ATTR SOURCETEXT ATTR NUMBER= 0x0010; 
// The character is a part of a language string constant. Example: "Hello World" 
const SOU RCE_TEXT ATTR SOURCETEXT ATTR STRING= 0x0020; 
// The character indicates the start of a function block 

30 const SOU RCE_TEXT_ATTR SOURCETEXT_ATTR_FUNCTION START = 
0x0040; 

TEXT_DOC_ATTR 

// Document attributes 
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typedef DWORD TEXT_DOC_ATTR; 

// Indicates that the document is read-only. 

const TEXT_DOC_ATTR TEXT DOC_ATTR_READONLY = 0x00000001 ; 
5 Parse Flags 

// Indicates that the text is an expression as opposed to a statement. This 
// flag may affect the way in which the text is parsed by some languages, 
const DWORD DEBUG_TEXT_ISEXPRESSION= 0x00000001; 
// If a return value is available, it will be used by the caller. 

10 const DWORD DEBUG, TEXT_RETURNVALUE= 0x00000002; 
// Don't allow side effects. If this flag is set, the evaluation of the 
// expression should change no runtime state, 
const DWORD DEBUG_TEXT_NOSIDEEFFECTS= 0x00000004; 
// Allow breakpoints during the evaluation of the text. If this flag is not 

15 // set then breakpoints will be ignored during the evaluation of the text- 
const DWORD DEBUG TEXT ALLOWBREAKPOINTS= 0x00000008; 
// Allow error reports during the evaluation of the text. If this flag is not 
// set then errors will not be reported to the host during the evaluation, 
const DWORD DEBUG_TEXT_ALLOWERRORREPORT= 0x00000010; 

20 

Language/Script Engine Debugging Interfaces 

Interfaces required by a language engine for debugging, browsing, & expression 
evaluation. 

25 lActiveScriptDebug 

// Provides a way for smart hosts to take over document management and for the 
Process Debug Manager to synchronize debugging of multiple language engines. 

i 

object, 

30 uuid(51973C10-CBOC-11d0-B5C9-0QA0244A0E7A), 
pointerdefault(unique) 

] 

interface lActiveScriptDebug : lUnknown 
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{ 

II Returns the text attributes for an arbitrary block of script text. Smart hosts 
// use this call to delegate GetText calls made on their IDebugDocumentText. 
HRESULT GetScriptTextAttributes( 
5 // The script block text. This string need not be null terminated, 
[in, size_is(uNumCodeChars)]LPCOLESTRpstrCode, 
// The number of characters in the script block text. 
pnlULONGuNumCodeChars, 

// See IActiveScriptParse::ParseScriptText for a description of this argument. 
10 [in]LPCOLESTRpstrDelimiter, 

// See IActiveScriptParse::ParseScriptText for a description of this argument. 
fin]DWORDdwFlags, 

// Buffer to contain the returned attributes. 

[in, out, size_is(uNumCodeChars)]SOURCE_TEXT_ATTR *pattr); 

15 

// Returns the text attributes for an arbitrary scriptlet. Smart hosts 
// use this call to delegate GetText calls made on their IDebugDocumentText. 
// Note: this call is provided because scriptlets tend to be expressions and 
// may have a different syntax than a script block. For many languages the 
20 implementation 

// will be identical to GetScriptTextAttributes. 
HRESULT GetScriptletTextAttributes( 

// The script block text. This string need not be null terminated, 
[in, size_is(uNumCodeChars)]LPCOLESTRpstrCode, 
25 // The number of characters in the script block text. 
[in]ULONGuNumCodeChars, 

// See IActiveScriptParse::AddScriptlet for a description of this argument. 
[in]LPCOLESTRpstrDelimiter, 

// See IActiveScriptParse::AddScriptlet for a description of this argument. 
30 [in]DWORDdwFlags, 

// Buffer to contain the returned attributes. 

[in, out, size is(uNumCodeChars)]SOURCE_TEXT_ATTR *pattr); 
// Used by the smart host to delegate 
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IDebugDocumentContext::EnumDebugCodeContexts. 
HRESULT EnumCodeContextsOfPosition( 
[in]DWORD dwSourceContext,// As provided to 
IActiveScriptParse::ParseScriptText 
5 // or IActiveScriptParse::AddScriptlet 

[in]ULONG uCharacterOffset,// character offset relative 
// to start of script text 

[in]ULONG uNumChars,// Number of characters in context 
// Returns an enumerator of code contexts. 
10 [out] lEnumDebugCodeContexts **ppescc); 

1 

lActiveScriptSiteDebug 

Implemented by smart hosts and is Ql-able from lActiveScriptSite. It provides the 
15 means by which a smart host takes over document management and participates 
in debugging. 

I 

object, 

20 uuid(51973C1 1-CB0C-1 1d0-B5C9-00A0244A0E7A), 
pointer_default(unique), 
local 

i 

interface lActiveScriptSiteDebug : I Unknown 
25 { 

II Used by the language engine to delegate 
IDebugCodeContext::GetSourceContext. 
HRESULT GetDocumentContextFromPosition( 
[in]DWORD dwSourceContext,// As provided to ParseScriptText 
30 //or AddScriptlet 

[in]ULONG uCharacterOffset,// character offset relative 
// to start of script block or scriptlet 

[in]ULONG uNumChars,// Number of characters in context 

// Returns the document context corresponding to this character-position range. 
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[out] IDebugDocumentContext **ppsc); 



// Returns the debug application object associated with this script site. Provides 
// a means for a smart host to define what application object each script belongs 
5 to. 

// Script engines should attempt to call this method to get their containing 
application 

// and resort to IProcessDebugManager::GetDefaultApplication if this fails. 
HRESULT GetApplication( 
10 [out] IDebugApplication **ppda); 

// Gets the application node under which script documents should be added 
// can return NULL if script documents should be top-level. 
HRESULT GetRootApplicationNode( 
15 [out] IDebugApplicationNode **ppdanRoot); 

// Allows a smart host to control the handling of runtime errors 
HRESULT OnScriptErrorDebug( 
// the runtime error that occurred 
20 [in] lActiveScriptErrorDebug *pErrorDebug, 

// whether to pass the error to the debugger to do JIT debugging 
[out]BOOL*pfEnterDebugger, 

// whether to call IActiveScriptSite::OnScriptError() when the user 
// decides to continue without debugging 
25 [outJBOOL *pfCallOnScriptErrorWhenContinuing); 

} 

lActiveScriptErrorDebug 

Provides document context information from compile and run time errors. 
30 [ 

object, 

uuid(51 973C1 2-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointer_default(unique) 

i 
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interface lActiveScriptErrorDebug : lActiveScriptError 
{ 

// Provides the document context for the associated error. The character-position 
range 

5 // should include the entire offending text. 
HRESULT GetDocumentContext( 
[out] IDebugDocumentContext **ppssc); 

// For runtime errors, provides the stack frame that is in effect. 
10 HRESULT GetStackFrame( 

[out] IDebugStackFrame **ppdsf); 

i 

IdebugCodeContext 

15 Abstraction reresenting a position in executable code as a virtual app counter. 

i 

object, 

uuid(51 973C1 3-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 
20 J 

interface IDebugCodeContext : lUnknown 

{ 

// Returns the document context associated with this code context. 

(I 

25 // Note: For text documents, the character-position 

// range should include the text for the entire statement. This allows the debugger 
IDE 

// to hilight the current source statement. 
HRESULT GetDocumentContext( 
30 [out] IDebugDocumentContext **ppsc); 

// Sets or clears a breakpoint at this code context. 

HRESULT SetBreakPoint( 

finl BREAKPOINT STATE bps); 
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IDebugExpression 

Abstract representation of an asynchronously evaluated expression. 

5 I 

object, 

uuid(51973C14-CB0C-11d0-B5C9-00A0244A0E7A), 
pointer_default(unique) 

1 

10 interface IDebugExpression : lUnknown 

{ 

// Begins the evaluation of the expression. 
HRESULT Start( 

// Provides an event driven means for indicating that the expression evaluation 
15 // is complete. If NULL, no events will be fired and the client will need to 
// poll the expression state using QuerylsComplete. 
[in] IDebugExpressionCallBack *pdecb); 

// Aborts the expression. Evaluation of an expression in progress will be stopped 
20 // at the earliest opportunity. If the expression is actually aborted, 
GetResultAsString 
// will return E_ABORT as phrResult. 
HRESULT Abort(void); 

25 // Returns S_FALSE if the operation is still pending. 
// Returns S_OK if the operation is complete. 
HRESULT QuerylsComplete(void); 

// Returns the result of the expression evaluation as a string and an HRESULT. 
30 Returns 

// EXPENDING if the operation is still pending. Returns S_OK and E ABORT in 
phrResult 

// when the operation was aborted with Abort. 
HRESULT GetResultAsString( 



71 



1001/017 

[outl HRESULT *phrResult, 



[out] BSTR *pbstrResult); 



// Returns the result of the expression evaluation as an 
5 // 1 Debug Property and an HRESULT. Returns 

// E PENDING if the operation is still pending. Returns S OK and E ABORT in 
phrResult 

// when the operation was aborted with Abort. 

10 HRESULT GetResultAsDebugProperty( 
[out] HRESULT *phrResult, 
[out] I Debug Property **ppdp); 

1 

15 IDebugExpressionContext 

Abstract representation of a context in which expressions can be evaluated. 

I 

object, 

uuid(51973C15-CB0C-11d0-B5C9-0QA0244A0E7A), 
20 helpstring("IDebugExpressionContext Interface"), 
pointer default(unique) 

i 

interface IDebugExpressionContext : lUnknown 

i 

25 // Creates an IDebugExpression for the specified text. 

HRESULT ParseLanguageText( 

// Provides the text of the expression or statement(s). 

[in]LPCOLESTRpstrCode, 

// Radix to use 
30 [in]UINTnRadix, 

// See IActiveScriptParse::ParseScriptText 

[inlLPCOLESTRpstrDelimiter, 

// See above flags. 

[inlDWORDdwFlags, 
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// Returns the IDebugExpression for the given text, 
[out] IdebugExpression **ppe 

)i 

5 // Returns a name and GUID for the langauge owning this context 
HRESULT GetLanguagelnfo ( 

[out] BSTR*pbstrLanguageName, //the name of the language 
[out] GUID*pLanguagelD // an unique id for this language 

n 

10 } 

IDebugExpressionCallback 

Provides status events related to progress of an IdebugExpression evaluation. 
I 

15 object, 

uuid(51973C16-CB0C-11d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 

1 

interface IDebugExpressionCallBack : lUnknown 
20 { 

// Indicates that the expression evaluation is complete. Note that 

// IDebugExpression::GetResultAsString can be called from within this event 

// handler. 

HRESULT onComplete(void); 
25 } 

IDebugStackFrame 

Abstraction representing a logical stack frame on the stack of a thread. 

i 

30 object, 

uuid(51973C17-CB0C-11d0-B5C9-00A0244A0E7A) > 
pointer_default(unique) 

i 

interface IDebugStackFrame : lUnknown 
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II Returns the current code context associated with the stack frame. 
HRESULT GetCodeContext( 
[out] IdebugCodeContext **ppcc); 
5 // Returns a short or long textual description of the stack frame. 

// Normally, when fLong if false, this will provide only the name of the 
// function associated with the stack frame. When fLong is true it may 
// also provide the parameter(s) to the function or whatever else is 
// relevant. 
10 HRESULT GetDescriptionString( 
[in] BOOL fLong, 
[out] BSTR *pbstrDescription); 

// Returns a short or long textual description of the language. When fLong 

// is false, just the language name should be provided, eg, "Pascal". When 
15 // fLong is true a full product description may be provided, eg, 

// "Gnat Software's Flaming Pascal v3.72". 

HRESULT GetLanguageString( 

[in] BOOL fLong, 

[out] BSTR *pbstrLanguage); 
20 // Returns the thread associated with this stack frame. 

HRESULT GetThread( 

[out] IdebugApplicationThread **ppat); 

// Returns a property browser for the current frame (locals, etc.) 
25 HRESULT GetDebugProperty( 

[out] IDebugProperty **ppDebugProp); 

1 

IDebugStackFrameSniffer 

30 Provides a means for enumerating logical stack frames known by a certain 
component. 

i 

object, 

uuid(51 973C1 8-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
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pointer_default(unique) 
1 

interface IDebugStackFrameSniffer : lUnknown 
{ 

5 // Returns an enumerator of stack frames for the current thread. Top of stack 
should 

// be returned first (the most recently pushed frame). 
HRESULT EnumStackFrames( 
[out] lenumDebugStackFrames **ppedsf); 
10 } 

IDebugStackFrameSnifferEx 

Provides a means for enumerating logical stack frames known by a certain 
component. 
15 [ 

object, 

uuid(51 973C1 9-CB0C-1 1 d0-B5C9-00A0244A0E7A) > 
pointerdefault(unique) 

i 

20 interface IdebugStackFrameSnifferEx : IDebugStackFrameSniffer 

// Returns an enumerator of stack frames for the current thread. 
// dwSpMin is the minimum address to begin enumerating stack frames 
// Stack frames before this address will be omitted from the enumeration. 
25 // Top of stack should be returned first (the most recently pushed frame). 
HRESULT EnumStackFramesEx( [in] DWORD dwSpMin, [out] 
lenumDebugStackFrames **ppedsf); 

ii 

30 IDebugSyncOperation 

Implemented by a language engine to expose expression evaluation. 

i 

object, 

uuid(51973C1a-CB0C-11d0-B5C9-00A0244A0E7A), 
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pointerdefault(unique), 

local 

1 

interface IDebugSyncOperation : lUnknown 
5 { 

// Get TargetThread is called by PPM to determine what thread 

// to call EvaluateQ in 

HRESULT GetTargetThread( 

[out] IdebugApplicationThread **ppatTarget); 

10 

// Execute is called synchronously by the PPM in the target thread. It 
// synchronously peforms the operation and returns. It returns E_ABORT if 
// the operation was aborted with InProgressAbortQ; 
HRESULT Execute( 
15 [out]IUnknown **ppunkResult); 

// InProgressAbortQ is called by the PPM, from within the debugger thread, 
// to cancel an operation which is in progress in another thread. The 
// operation should be completed or error out with E_ABORT as soon as 
20 // possible. E_NOTIMPL can be returned if the operation cannot be cancelled. 
HRESULT InProgressAbort(void); 

1 



IDebugAsyncOperation 

25 Implemented by the PPM and obtained by the language engine 

i 

object, 

uuid(51973C1b-CB0C-11d0-B5C9-00A0244A0E7A), 
pointerdefault(unique), 
30 local 

1 

interface IPebugAsyncOperation : lUnknown 

{ 

HRESULT GetSyncDebugOperation( 
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[out] IDebugSyncOperation **ppsdo); 



// StartQ causes the asynchronous operation to begin. It asynchronously 
// causes IDebugSyncOperation::Execute() to be called in the thread obtained 
5 //from IDebugSyncOperation::GetTargetThread(). It should only 
// be called from within the debugger thread, or it will not return until 
// the operation is complete (it degenerates to synchronous). 
// Returns E_UNEXPECTED if an operation is already pending. 
HRESULT StartQDebugAsyncOperationCallBack *padocb); 

10 

// AbortQ causes InProgressAbortQ to be called on the IDebugSyncOperation 
// object. It is normally called from within the debugger thread to cancel 
// a hung operation. If the abort happens before the request completes, 
// GetResultQ will return E ABORT. E NOTIMPL may be returned from this 
15 // function if the operation is not cancellable. 
HRESULT Abort(void); 

// QuerylsCompleteQ returns S_OK if the operation is complete; otherwise it 
// returns S FALSE; 
20 HRESULT QuerylsComplete(void); 

// If the request is complete, returns the HRESULT and object parameter 
// returned from IDebugSyncOperation::Execute(). Otherwise, returns 
// E PENDING. 
25 HRESULT GetResult( 

[out] HRESULT *phrResult, 
[out] lUnknown **ppunkResult); 

i 

30 IDebugAsyncOperationCallBack 

Used to signal events from an IdebugAsyncOperation. 

i 

object, 

uuid(51 973C1 c-CBOC-1 1 d0-B5C9-00A0244A0E7A), 
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pointer_default(unique), 
local 

i 

interface IDebugAsyncOperationCallBack : I Unknown 
5 { 

// onCompleteQ is fired by the AsyncDebugOperation when a result is available. 
// The event is fired in the debugger thread. 
HRESULT onComplete(void); 

1 

10 

lEnumDebugCodeContexts 

Used to enumerate the conde contexts corresponding to a document context. 
I 

object, 

15 uuid(51973C1d-CB0C-11d0-B5C9-00A0244A0E7A) > 
helpstring( H IEnumPebugCodeContexts Interface"), 
pointer_default(unique) 

i 

interface lEnumDebugCodeContexts : lUnknown { 
20 [local] 

HRESULT stdcall Next( 
[in] ULONG celt, 

[out] IdebugCodeContext **pscc, 
[out] ULONG *pceltFetched); 
25 HRESULT Skip( 
[in] ULONG celt); 
HRESULT Reset(void); 
HRESULT Clone( 

[out] lenumDebugCodeContexts **ppescc); 
30 } 

DebugStackFrameDescriptor 

Used to enumerate stack frames and merge output from several enumerators (on 
the same thread). dwMin and dwLim provide a machine dependent representation 
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of the range of physical addresses associated with this stack frame. This is used 
by the process debug manager to sort the stack frames from multiple script 
engines. 

By convention, stacks grow down and, as such, on architectures where stacks 
5 grow up the addresses should be twos-complemented. 

The punkFinal is used during enumerator merging. If punkFinal is non-null, It 
indicates that the that the current enumerator merging should stop and a new one 
should be started. The object indicates how the new enumeration is to be started. 

10 typedef struct tagDebugStackFrameDescriptor 
{ 

IDebugStackFrame *pdsf; 
DWORD dwMin; 
DWORD dwLim; 
15 BOOL fFinal; 

lUnknown *punkFinal; 

} DebugStackFrameDescriptor; 

lEnumDebugStackFrames 

20 Used to enumerate the stack frames corresponding to a thread. 

i 

object, 

uuid(51973C1e-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("IEnumDebugStackFrames Interface"), 
25 pointerdefault(unique) 

i 

interface lEnumPebugStackFrames : lUnknown 

{ 

[local] 

30 H RESULT stdcall Next( 
[in] ULONG celt, 

[out] DebugStackFrameDescriptor *prgdsfd, 
[out] ULONG *pceltFetched); 
HRESULT Skip( 
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fin] ULONG celt); 
HRESULT Reset(void); 
HRESULT Clone( 

[out] lEnumDebugStackFrames **ppedsf); 
5 1 

Smart Host Interfaces 

Below are th edetails of the inerfaces implemented by a smart host. As 
mentioned earlier, it is possible to avoid implementing these interfaces by using 
10 the smart host helper interfaces. 

DebugDocumentlnfo 

Provides information on a document, which may or may not be instantiated. 

i 

15 object, 

uuid(51973C1f-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("l DebugDocumentlnfo Interface"), 
pointer_default(unique) 

i 

20 interface I DebugDocumentlnfo : I Unknown { 

// Returns the specified name for the document. If the indicated name is 

// not known, E FAIL is returned. 

HRESULT GetName( 

[in] DOCUMENTNAMETYPE dnt, 
25 [out] BSTR *pbstrName); 

// Returns a CLSID describing the document type. This allows the debugger IDE 

// to host custom viewers for this document, returns CLSID_NULL if this document 

// does not have viewable data. 

HRESULT GetDocumentClassld( 
30 [out] CLSID *pclsid Document); 

1 

IDebugDocumentProvider 
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Provides the means for instantiating a document on demand. This indirect means 
for instanciating a document: 

1. Allows lazy loading of the document. 

5 

2. AIIOWS the document object to live at the debugger IDE. 

3-Allows more then one way of getting to the identical document object. 
This effectively segregates the document from its provider; this allows the provider 
10 to carry additional runtime context information. 

i 

object, 

uuid(51 973C20-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
15 helpstring("IDebugDocumentProvider Interface"), 
pointer_default(unique) 

interface IDebugDocumentProvider : IDebugDocumentlnfo { 
// Causes the document to be instantiated if it does not already exist. 
20 HRESULT GetDocument( 

[out] IdebugDocument **ppssd); 

} 

IDebugDocument 

25 I 

object, 

uuid(51 973C21 -CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointer default(unique) 

1 

30 interface IDebugDocument : IDebugDocumentlnfo { 

1 

IDebugDocumentText 

The interface to a text only debug document. 
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Conventions: 



1 .Both character positions and line numbers are zero based. 

5 2.Character-positions represent character offsets; they do not represent byte or 
word offsets. For Win32, a character-position is an Unicode offset- 
Note: the use of line-number based text management is not recommended; 
instead it is recommended that character-position based management be used. 
10 The line to character-position mapping functions described in this interface may 
be removed. 

1 

object, 

15 uuid(51973C22-CB0C-11d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 

i 

interface IDebugDocumentText : I Debug Document { 
// Returns the attributes of the document. 
20 HRESULT GetDocumentAttributes( 
[out]TEXT_DOC_ATTR *ptextdocattr); 

// Returns the size of the document. 
HRESULT GetSize( 

25 [out] ULONG *pcNumLines, // NULL means do not return the number of lines. 
[out] ULQNG *pcNumChars); // NULL means do not return the number of 
characters. 

// Returns character-position corresponding to the first character of a line. 
30 HRESULT GetPositionOfLine( 
[in] ULONG cLineNumber, 
[out] ULONG *pcCharacterPosition); 



// Returns the line-number and, optionally, the character offset within the line 
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// that corresponds to the given character-position. 
HRESULT GetLineOfPosition( 
[in] ULONG cCharacterPosition, 
[out] ULONG *pcLineNumber, 
5 [out] ULONG *pcCharacterOffsetlnLine); // NULL means do not return a value. 

// Retrieves the characters and/or the character attributes associated with 
// a character-position range; where a character position range is specified by 
// a character-position and a number of characters. 
10 HRESULT GetText( 

[in] ULONG cCharacterPosition, 

// Specifies a character text buffer. NULL means do not return characters, 
[in, out, length_is(*pcNumChars), size_is(cMaxChars)] WCHAR *pcharText, 
// Specifies a character attribute buffer. NULL means do not return attributes. 
15 [in, out, length_is(*pcNumChars), sizeJs(cMaxChars), ptr] 
SOU RC E_TEXT_ATTR *pstaTextAttr, 

// Indicates the actual number of characters/attributes returned. Must be set to 
zero 

// before the call. 
20 [in, out] ULONG *pcNumChars, 

// Specifies the number maximum number of character desired, 
[in] ULONG cMaxChars); 

// Returns the character-position range corresponding to a document context. The 
25 document 

// context provided must be associated with this document. 

HRESULT GetPositionOfContext( 

[in] IDebugDocumentContext *psc, 

[out] ULONG *pcCharacterPosition, 
30 [out]ULONG *cNumChars); 

// Creates a document context object corresponding to the provided character 
position range. 

HRESULT GetContextOfPosition( 
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[in] ULONG cCharacterPosition, 

[in] ULONG cNumChars, 

[out] IDebugDocumentContext **ppsc); 

1 

5 

IDebugDocumentTextEvents 

Provides events indicating changes to the associated text document. Note: The 
text alterations are reflected in the document at the time the events on this 
interface are fired. Event handlers may retrieve the new text using 
10 IDebugDocumentText. 

i 

object, 

uuid(51973C23-CB0C-11d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 
15 J 

interface IDebugDocumentTextEvents : lUnknown 

II Indicates that the underlying document has been destroyed and is no longer 
valid. 

20 HRESULT onDestroy(void); 

// Indicates that new text has been added to the document. Example: progressive 

loading 

// of HTML. 
25 IJ_ 

HRESULT onlnsertText( 

// The position where the new text is inserted. 

[in] ULONG cCharacterPosition, 

// The number of characters that have been inserted. 
30 [in] ULONG cNumTolnsert); 

// Indicates that text has been removed from the document. 
HRESULT onRemoveText( 

// The character-position of the first character removed. 
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[in] ULONG cCharacterPosition, 

// The number of characters removed. 

[in] ULONG cNumToRemove); 

5 // Indicates that text has been replaced. 
HRESULT onReplaceText( 

// The starting character-position of the character-position range 
// that is being replaced, 
[in] ULONG cCharacterPosition, 
10 // The number of characters replaced, 
[in] ULONG cNumToReplace); 

// Indicates that the text attributes associated with the underlying character- 
position 
15 // range has changed. 

HRESULT onUpdateTextAttributes( 

// The character-position of the first character whose attributes have changed, 
[in] ULONG cCharacterPosition, 
// The number of characters in the range. 
20 [in] ULONG cNumToUpdate); 

// Indicates that the document attributes have changed. 
HRESULT onUpdatePocumentAttributes( 
// The new document attributes. 
25 [in] TEXT_DOC_ATTR textdocattr); 

} 

IDebugDocumentHelper 

IDebugDocumentHelper greatly simplifies the task of creating a smart host for 
30 ActiveDebugging. IDebugDocumentHelper automatically provides 
implementations for IDebugDocumentProvider, IDdebugDocument, 
IDebugDocumentText, IDebugDocumentContext, IDebugDocumentTextEvents, 
and many of the other interfaces necessary for smart hosting. To be a smart host 
using IDebugDocumentHelper, a host application only to do only three two things: 
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(1) CoCreate an IProcessDebugManager and use it to add your application to the 
list of debuggable applications. 

(2) create an IDebugDocumentHelper for each host document and make the 
appropriate calls to define the document name, parent document, text, and script 

5 blocks. 

(3) Implement lActiveScriptSiteDebug on your lActiveScriptSite object 
(implemented already for Active Scripting. The only non-trivial method on 
lActiveScriptSiteDebug simply delegates to the helper. 

Additionally, the host can optionally implement IDebugDocumentHost if it needs 
10 additional control over syntax color, document context creation, and other 
extended functionality. 

The main limitation on the smart host helper is that can only handle documents 
whose contents change or shrink after they have been added. For many smart 
hosts, however, the functionality it provides is exactly what is needed. Below we 
15 go into each of the steps in more detail. 

Create an Application Object 

Before the smart host helper can be used, it is necessary to create an v 
IDebugApplication object to represent your application in the debugger. The steps 
20 for creating an application object are as follows: 

(1) Create an instance of the process debug manager using CoCreatelnstance. 

(2) Call IProcessDebugManager::CreateApplication(). 

(3) Set the name on the application using SetNameQ. 

(4) Add the application object to the list of debuggable applications using 
25 AddApplicationQ. 

Below is code to do this, minus error-check and other niceties. 

CoCreatelnstance(CLSID_ProcessDebugManager, NULL, 
CLSCTX_INPROC_SERVER | CLSCTX INPROC HANDLER I 
30 CLSCTX_LOCAL_SERVER, 

IIDJProcessDebugManager, (void **)&g_ppdm); 

g_ppdm->CreateApplication(&g_pda); 

g_pda->SetName(L"My cool application"); 

g ppdm->AddApplication(g pda, &g_dwAppCookie); 
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Using IDebugDocumentHelper 

The minimal sequence of steps for using the helper is as follows: 

(1) For each host document, create a helper using IprocessDebugManager :: 
5 CreatePebugPocumentHelper. 

(2) Call Init on the helper, giving the name, document attributes, etc. 

(3) Call Attach with parent helper for the document (or NULL if the document is 
the root) to define the position of the document in the tree and make it visible to 
the debugger 

10 (4) Call AddDBCSTextQ or AddUnicodeTextQ to define the text of the document. 
These can be called multiple times if document is downloaded incrementally, as in 
the case of a browser. 

(5) Call DefineScriptBlock to define the ranges for each script block and the 
associated script engines. 

15 

Implementing lActiveScriptSiteDebug 

To implement GetDocumentContextFromPosition, get the helper corresponding to 
the given site, then get the starting document offset for the given source context, 
as follows: 

20 pddh->GetScriptBlocklnfo(dwSourceContext l NULL, &ulStartPos, NULL); 
Next, use the helper to create a new document context for the given character 
offset: 

pddh->CreatePebugPocumentContext(ulStartPos + uCharacterOffset, cChars, 
&pddcNew); 
25 To implement GetRootApplicationNode, simply call 

IPebugApplication::GetRootNode. To implement GetDebugApplication, simply 
return the IPebugApplication you initially created using the process debug 
manager. 
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The optional IDebugDocumentHost interface 

The host can provide an implementation of IDebugDocumentHost using 
lDebugDocumentHelper::SetHost that gives it additional control over the helper. 
5 Here are some of the key things the host interface allows you to do: 

(1 ) Add text using AddDeferredText so that the host doesn't have to provide the 
actual characters immediately. When the characters are really needed, the helper 
will call IDebugDocumentHost::GetDeferredCharacters on the host. 

(2) Override the default syntax coloring provided by the helper. The helper will call 
10 IDebugDocumentHost::GetScriptTextAttributes when it needs to know the coloring 

for a range of characters, falling back on its default implementation if the host 
return E_NOTIMPL. 

(3) Providing a controlling unknown for document contexts created by the helper 
my implementing IDebugDocumentHost::OnCreateDocumentContext. This allows 

15 the host to override the functionality of the default document context 
implementation. 

(4) Provide a path name in the file system for the document. Some debugging Uls 
will use this to permit the user to edit and save changes to the document. 
IDebugDocumentHost::NotifyChanged will be called to notify the host after the 

20 document has been saved. 

i 

object, 

uuid(51973C26-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("IDebugDocumentHelper Interface"), 
25 pointer_default(unique) 

i 

interface IPebugPocumentHelper : lUnknown 

// Initialize a debug doc helper with the given name and 
30 // initial attributes. 

IJ_ 

II Note: The document will not actually appear in the tree 
// until Attach is called. 
HRESULT lnit( 
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[in] IDebugApplication *pda, 
[in, string]LPCOLESTR pszShortName, 
[in, string]LPCOLESTR pszLongName, 
[in]TEXT_DOC ATTR docAttr 

li 

II Add the document to the doc tree, using pddhParent as the parent. 
// If the ppdhParent is NULL, the document will be top-level. 
HRESULT Attach([in] IdebugDocumentHelper *pddhParent); 

// Remove the document from the doc tree. 



HRESULT DetachQ; 

// Add the given set of Unicode characters to end of the document to generate 
15 // IDebugDocumentTextEvent notifications. 

// If this method is called after Add DeferredText has been called, 
// E FAIL will be returned. 



HRESULT AddUnicodeText( 
[in, string] LPCOLESTR pszText 
20 )] 

II Add the given set of DBCS characters to end of the document. 
// (This will generate IDebugDocumentTextEvent notifications.) 
// If this method is called after Add DeferredText has been called, 
25 // E FAIL will be returned. 



HRESULT AddDBCSText( 
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[in, string] LPCSTR pszText 
)i 

// Set the DebugDocumentHost interface. 
5 // If provided, this interface will be used for 

// smart-host syntax coloring, fetching deferred text, and returning 
// controlling unknowns for newly created document contexts. 
HRESULT SetDebugDocumentHost( 
[in] IdebugDocumentHost * pddh 
10 )] 

II Notify the helper that the given text is available, but don't actually provide the 
characters 

// This allows the host to defer providing the characters unless they are actually 
15 needed, 

// while still allowing the helper to generate accurate notifications and size 
information. 

// dwTextStartCookie is a cookie, defined by the host, that represents the starting 
// position of the text. For example, in a host that represents text in DBCS, the 
20 cookie 

// could be a byte offset. This cookie will be provided in subsequent calls to 
GetText. 

// NB: It is assumed that a single call to GetText can get characters from multiple 
calls 

25 // to AddDeferredText. The helper classes may also ask for the same range of 
deferred 

// characters more than once. It is an error to mix calls to AddDeferredText with 
calls to 

// AddUnicodeText or AddDBCSText-- Doing so will cause E_FAIL to be returned. 
30 HRESULT AddDeferredText( 

[in] ULONG cChars,// number of (Unicode) characters to add 
[in] DWORD dwTextStartCookie 

// host-defined cookie representing the starting position of the text. 
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// Notify the helper that a particular range of characters is a script block handled 

by 

// the given script engine. All syntax coloring and code context lookups for that 
5 // range will be delegated to that script engine. This method would be used by a 
smart host whose documents contained embedded script blocks, or by a language 
// engine containing embedded scripts for other languages. DefineScriptBlock 
should 

// be called after the text has been added (via AddDBCSText, etc) but before the 
10 // script script block has been parsed (via lActiveScriptParse). 

HRESULT DefineScriptBlock( 

[in] ULONG ulCharOffset, 

[in] ULONG cChars, 

[in] lActiveScript* pas, 
15 [in] BOOL fScriptlet, 

[out] DWORD* pdwSourceContext 

// Set the default attribute to use for text that is not in a script block. If not explicitly 
20 // set, the default attributes for text outside of a script block is 

// OURCETEXT_ATTR_NONSOURCE. This would allow, for example, for text 
// outside of script blocks to be colored grey and marked read-only. 
HRESULT SetDefaultTextAttr(SOURCE_TEXT_ATTR staTextAttr); 

25 // Explicilty set the attributes on a range of text, overriding any other attributes 

// on that text. It is an error to set the attributes on a text range that has not 

// yet been added using AddText. 

HRESULT SetTextAttributes( 

[in] ULONG ulCharOffset, 
30 [in] ULONG cChars, 

[in, length_is(cChars), size_is(cChars)] 

SOURCE_TEXT_ATTR* pstaTextAttr); 

// Set a new long name for the document 
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HRESULT SetLongName( 

[in, string] LPCOLESTR pszLongName); 

// Set a new short name for the document 
5 HRESULT SetShortName( 

[in, string] LPCOLESTR pszShortName); 

// Define a new set of document attributes 
HRESULT SetDocumentAttr( 
10 [in] TEXT_DOC ATTR pszAttributes 

)1 

II Return the debug application node corresponding to this document 
HRESULT GetDebugApplicationNode( 
15 [out] IdebugApplicationNode **ppdan); 

// Once a script block has been defined, this method allows the 
// associate range and script engine to be retrieved: 
HRESULT GetScriptBlocklnfo( 
20 [in] DWORD dwSourceContext, 
[oufJIActiveScript** ppasd, 
[out] ULONG *piCharPos, 
[out]ULONG *pcChars); 

25 // Allows the host to create a new debug document context 
HRESULT CreateDebugDocumentContext( 
[in]ULONG iCharPos, 
[in]ULONG cChars, 

[out] IdebugDocumentContext ** ppddc); 

30 

// Bring this document to the top in the debugger Ul. 
// If the debugger isn't started already, start it now. 
HRESULT BringDocumentToTopQ; 
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// Bring the given context in this document to the top in the debugger Ul. 
HRESULT BringDocumentContextToTop (IDebugDocumentContext *pddc); 

5 IDebugDocumentHost 

The interface from the IdebugDocumentHelper back to the smart host or 
language engine. This interface exposes hast specific functionality such as 
syntax coloring. 

I 

10 object, 

uuid(51 973C27-CBQC-1 1 d0-B5C9-Q0A0244A0E7A), 
helpstring("IDebugDocumentHost Interface"), 
pointer_default(unique) 

i 

15 interface IDebugDocumentHost : I Unknown 

i 

// Return a particular range of characters in the original host document, 
// added using AddDeferredText. 

20 // It is acceptable for a host to return E NOTIMPL for this method, 
// as long as the host doesn't call AddDeferredText. 

/]_ 

II (Note that this is text from the _original_ document. The host 
// does not need to be responsible for keeping track of edits, etc.) 
25 HRESULT GetDeferredText( 

[in] DWORD dwTextStartCookie, 

// Specifies a character text buffer. NULL means do not return characters. 
[in, out, length_is(*pcNumChars), size_is(cMaxChars)] WCHAR *pcharText, 
// Specifies a character attribute buffer. NULL means do not return attributes. 
30 [in, out, length_is(*pcNumChars), size_is(cMaxChars)] SOURCE TEXT ATTR 
*pstaTextAttr, 

// Indicates the actual number of characters/attributes returned. Must be set to 
zero 

// before the call. 
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[in, out] ULONG *pcNumChars, 

// Specifies the number maximum number of character desired, 
[in] ULONG cMaxChars); 

5 . // Return the text attributes for an arbitrary block of document text. 
// It is acceptable for hosts to return E_NOTIMPL, in which case the 
// default attributes are used. 
HRESULT GetScriptTextAttributes( 

// The script block text. This string need not be null terminated. 
10 [in, size_is(uNumCodeChars)]LPCOLESTRpstrCode, 
// The number of characters in the script block text. 
[in]ULONGuNumCodeChars, 

// See IActiveScriptParse::ParseScriptText for a description of this argument. 
[in]LPCOLESTRpstrDelimiter, 
15 // See IActiveScriptParse::ParseScriptText for a description of this argument. 
[in]DWORDdwFlags, 

// Buffer to contain the returned attributes. 

[in, out, size_is(uNumCodeChars)]SOURCE_TEXT_ATTR *pattr); 

20 // Notify the host that a new document context is being created and allow the host 
// to optionally return a controlling unknown for the new context. 

IJ_ 

II This allows the host to add new functionality to the helper-provided document 
// contexts. It is acceptable for the host to return E_NOTIMPL or a null outer 
25 // unknown for this method, in which case the context is used "as is". 
HRESULT OnCreateDocumentContext( 
[out] lUnknown** ppunkOuter); 

// Return the full path (including file name) to the document's source file. 
30 //*pflsOriginalPath is TRUE if the path refers to the original file for the document. 
//*pflsOriginalPath is FALSE if the path refers to a newly created temporary file 
//Returns E FAIL if no source file can be created/determined. 
HRESULT GetPathName( 
[out] BSTR *pbstrLongName, 
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[out] BOOL *pflsOriginalFile); 



// Return just the name of the document, with no path information. 
//(Used for "Save As...") 
5 HRESULT GetFileName( 

[out] BSTR *pbstrShortName); 

// Notify the host that the document's source file has been saved and 
// that its contents should be refreshed. 
10 HRESULT NotifyChangedQ; 

li 

IDebugDocumentContext 

i 

15 object, 

uuid(51 973C28-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 

1 

interface IDebugDocumentContext : I Unknown 
20 { 

II Returns the document that contains this context. 
HRESULT GetDocumenU 
[out] IDebugDocument **ppsd); 

25 // Enumerates the code contexts associated with this document context. Generally 

// there will only be one code context but there are important exceptions, such as 

// include file or templates (in C++). 

HRESULT EnumCodeContexts( 

[out] lEnumDebugCodeContexts **ppescc); 
30 } 

Debugger Ul interfaces 

Below are the interfaces that allow other components to launch and interface with 
the debugger Ul. 
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IDebugSessionProvider 

The primary interface provided by a debugger IDE to enable host and language 
initiated debugging. Its sole purpose is to establish a debug session for a running 
application. 

5 cpp_quote( "EXTERN C const CLSID CLSID_DefaultDebugSessionProvider; ,, ) 
I 

object, 

uuid(51973C29-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("IDebugSessionProvider Interface"), 
10 pointerdefault(unique) 

1 

interface IDebugSessionProvider : I Unknown 
i 

// Initiates a debug session with the specified application. The debugger should 
15 // call IRemoteDebugApplication::ConnectDebugger before returning from this call. 
HRESULT StartDebugSession( 
[in] IremoteDebugApplication *pda); 

20 lApplicationDebugger 

This is the primary interface exposed by a debugger IDE. 

i 

object, 

uuid(51 973C2a-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
25 helpstring("IApplicationDebugger Interface"), 
pointer_default(unique) 

i 

interface lApplicationDebugger : lUnknown 

i 

30 // Indicates if the debugger is alive. Should always return S_OK. If the debugger 
// has rudely shut down COM will return an error from the marshalling proxy. 
HRESULT QueryAlive(void); 

// Provides a mechanism for hosts and language engines running out-of-process 
to the 
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// debugger to create objects in the debugger process. This can be used for any 
purpose, 

// including extending the debugger Ul. This method simply delegates to 
CoC reate I n sta n ce . 
5 HRESULT CreatelnstanceAtDebugger( 

[in]REFCLSID rclsid,// Class identifier (CLSID) of the object 
[injIUnknown *pUnkOuter,// Object is or isn't part of an aggregate 
[in]PWORP dwClsContext,// Context for running executable code 
[in]REFIID hid,// Interface identifier 
10 [out, iid_is(riid)]l Unknown **ppvObject); 

// Points to requested interface pointer. This method is called when 
IdebugApplication :: 

// DebugOutput is called. The debugger can use this to display the string in an 
output 
15 // window. 

HRESULT onDebugOutput( 
[in] LPCOLESTR pstr); 

// This method is called when a breakpoint is hit. The application will remain 

// suspended until the debugger IDE calls 
20 IDebugApplication::ResumeFromBreakPoint. 

HRESULT onHandleBreakPoint( 

// Indicates the thread in which the breakpoint occured. 

[in] IremoteDebugApplicationThread *prpt, 

// Indicates the reason for the breakpoint. 
25 [in]BREAKREASON br, 

// optional runtime error info (for when br == BREAKREASON ERROR) 

[in] lactiveScriptErrorDebug *pError); 

// This method is called when IPebugApplication::Close is called. 
30 HRESULT onClose(void); 

// Handle a custom event. 

// The semantics of the GUIP and lUnknown are entirely application/debugger 
defined 
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// This method may return E NOTIMPL. 
HRESULT onDebuggerEvent( 
[inlREFIID riid, 
[in]l Unknown *punk); 

lApplicationDebuggerUI 

This is a secondary interface exposed by some debugger IDE that allows an 
external component to have additional control over the debuggers Ul. 
10 [ 

object, 

uuid(51 973C2b-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IApplicationDebuggerUI Interface"), 
pointer_default(unique) 
15 J 

interface lApplicationDebuggerUI : lUnknown 

{ 

II Bring the window corresponding to the given debug document to the front. 
// Returns E INVALIDARG if the document is not known. 
20 HRESULT BringDocumentToTop([in] IdebugDocumentText * pddt); 

// Bring the window containing the given doc context to the front, 
// and scroll it to the correct location. 
// Returns E INVALIDARG if the context is not known. 
25 HRESULT BringDocumentContextToTop([in] IdebugDocumentContext * pddc); 

IMachineDebugManager 

The primary interface to the Machine Debug Manager. 
30 cpp_quote( "EXTERN C const CLSID CLSID_MachineDebugManager;") 

I 

object, 

u u id(51 973C2C-CB0C- 1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IMachinePebugManager Interface"), 
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pointerdefault(unique) 
1 

interface IMachineDebugManager : lUnknown 
1 

5 // Adds an application to the running application list. This method is called by the 
// process debug manager whenever IProcessDebugManager::AddApplication is 
called. 

HRESULT AddApplication( 
[in] IremoteDebugApplication *pda, 
10 [out] DWORD *pdwAppCookie); 

// Removes an application from the running application list. This method is called 
by the 

// process debug manager whenever 
IProcessDebugManager::RemoveApplication is called. 
15 HRESULT RemoveApplication( 
[in] DWORD dwAppCookie); 

// Returns an enumerator of the current list of running applications. Used by the 
debugger 

// IDE to display and attach applications for debugging purposes. 
20 HRESULT EnumApplications( 

[out] lenumRemoteDebugApplications **ppeda); 

)i 

IMachineDebugManagerCookie 

25 I 

object, 

uuid(51973C2d-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstringC'IMachineDebugManagerCookie Interface"), 
pointer_default(unique) 
30 1 

interface IMachineDebugManagerCookie : lUnknown 

// Adds an application to the running application list. This method is called by the 
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// process debug manager whenever IProcessDebugManager::AddApplication is 
called. 

HRESULT AddApplication( 
[in] IRemoteDebugApplication *pda, 
5 [in] DWORD dwPebugAppCookie, 
[out] DWORD *pdwAppCookie); 

// Removes an application from the running application list. This method is called 
by the 

// process debug manager whenever 
10 IProcessDebugManager::RemoveApplication is called. 
HRESULT RemoveApplication( 
[in] DWORD dwPebugAppCookie, 
[in] DWORD dwAppCookie); 

// Returns an enumerator of the current list of running applications. Used by the 
15 debugger 

// IDE to display and attach applications for debugging purposes. 

HRESULT EnumApplications( 

[out] lEnumRemoteDebugApplications **ppeda); 

]1 

20 

ImachineDebugManagerEvents 

This event interface is used to signal changes in the running application list 
maintained by the machine debug manager. It can be used by the debugger IDE 
to display a dynamic list of applications. 
25 { 

object, 

uuid(51 973C2e-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IMachineDebugManagerEvents Interface"), 
pointer_default(unique) 
30 1 

interface IMachineDebugManagerEvents : lUnknown 

{ 

// Indicates that a new application has appeared on the running application list. 
HRESULT onAddApplication( 
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finl IRemoteDebugApplication *pda, 
fin] DWORD dwAppCookie); 

// Indicates that an application has been removed from the running application list. 
HRESULT onRemoveApplication( 
5 [in] IRemoteDebugApplication *pda, 
[in] DWORD dwAppCookie); 

11 

Process Debug Manager Interfaces 

10 

IProcessDebugManager 

The primary interface to the process debug manager. 

cpp_quote( "EXTERN_C const CLSID CLSID_ProcessDebugManager;") 

I 

15 object, 

uuid(51 973C2f-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IPrbcessDebugManager Interface"), 
pointer_default(unique), 
local 
20 J 

interface IProcessDebugManager : lUnknown 
{ 

II Creates a new debug application object. The new object is not added to the 
// running application list and has no name. 
25 HRESULT CreateApplication( 
[out] IDebugApplication **ppda); 

// Returns a default application object for the current process, creating one and 
adding 

// it to the running application list if necessary. Language engines should use this 
30 // application if they are running on a host that does not provide an application. 
HRESULT GetDefaultApplication( 
[out] IDebugApplication **ppda); 

// Adds an application to the running application list in the machine debug 
manager. 
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HRESULT AddApplication( 
[in] IDebugApplication *pda, 

// Returns a cookie used to remove the application from the machine debug 
manager. 
5 [out] DWORD *pdwAppCookie); 

// Removes an application from the running application list. 
HRESULT RemoveApplication( 
// The cookie provided by Add Application. 
[in] DWORD dwAppCookie); 
10 HRESULT CreateDebugDocumentHelper( 
[in] lUnknown *punkOuter, 
[out] IdebugDocumentHelper ** pddh); 

h. 

15 IRemotePebugApplication 

An abstraction representing a running application. It need not correspond to an 
OS process. Applications are the smallest debuggable unit; that is, the debugger 
IDE normally targets an application for debugging. 

20 The application object is normally implemented by the Process Debug Manager. 

i 

object, 

uuid(51 973C30-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IRemotePebugApplication Interface"), 
25 pointerdefault(unique) 

1 

interface IRemotePebugApplication : lUnknown 

{ 

// Continue an application which is currently in a breakpoint. 
30 HRESULT ResumeFromBreakPoint( 

// For stepping modes, the thread which is to be affected by the stepping mode. 

[in] IremoteDebugApplicationThread *prptFocus, 

// The action to take (step mode, etc.) upon resuming the application 

[in] BREAKRESUMEACTION bra, 
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// the action to take in the case that we stopped because of an error 
[in] ERRORRESUMEACTION era); 

// Causes the application to break into the debugger at the earliest opportunity. 
Note 

5 // that a long time may elapse before the application actually breaks, particularly if 
// the application is not currently executing script code. 
HRESULT CauseBreak(void); 

// Connects a debugger to the application. Only one debugger may be connected 
at a 

10 // time; this method fails if there is already a debugger connected 
HRESULT ConnectDebugger( 
[in] lapplicationDebugger *pad); 

// Disconnects the current debugger from the application. 
HRESULT DisconnectDebugger(void); 
15 // Returns the current debugger connected to the application. 
HRESULT GetDebugger( 
[out] lapplicationPebugger **pad); 

// Provides a mechanism for the debugger IPE, running out-of-process to the 

// application, to create objects in the application process. 
20 // This method simply delegates to CoCreatelnstance. 

HRESULT CreatelnstanceAtApplication( 

[in] REFCLSIP rclsid, // Class identifier (CLSIP) of the object 

// Note: This parameter may have to be removed. 

[in]IUnknown *pUnkOuter, // Object is or isn't part of an aggregate 
25 [in]PWORP dwClsContext, // Context for running executable code 

[in]REFIIP hid,// Interface identifier 

[out, iid_is(riid)]IUnknown **ppvObject); 

// Points to requested interface pointer 

// Indicates if the application is alive. Should always return S_OK. If the application 
30 // process has rudely shut down COM will return an error from the marshalling 
proxy. 

HRESULT QueryAlive(void); 

// Enumerates all threads known to be associated with the application. 
// New threads may be added at any time. 
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HRESULT EnumThreads( 

[out] lenumRemoteDebugApplicationThreads **pperdat); 
// Returns the application node under which all nodes associated with the 
// application are added. 
5 HRESULT GetName( 
[outjBSTR *pbstrName); 
// Returns a node for the application 
HRESULT GetRootNode( 
[out] IDebugApplicationNode **ppdanRoot); 
10 // Returns an enumerator that lists the global expression 
// contexts for all languages running in this application 
HRESULT EnumGlobalExpressionContexts ( 
[out] lenumDebugExpressionContexts **ppedec); 

15 

IDebugApplication 

This interface is an extension of IremoteDebugApplication, exposing non- 
remotable methods for use by language engines and hosts. 

I 

20 object, 

uuid(51973C32-CB0CM1d0-B5C9-00A0244A0E7A), 
helpstring("IDebugApplication Interface"), 
pointerdefault(unique), 
local 
25 J 

interface IDebugApplication : IRemoteDebugApplication 

i 

// Sets the name of the application that is returned in subsequent calls 
// to IRemoteDebugApplication::GetName. 
30 HRESULT SetName( 

[in]LPCOLESTR pstrName); 

//This method is called by language engines, in single step mode, just before they 
// return to their caller. The process debug manager uses this opportunity to notify 
all 
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// other script engines that they should break at the first opportunity. This is how 
// cross language step modes are implemented. 
HRESULT StepQutComplete(void); 

// Causes the given string to be displayed by the debugger IDE, normally in an 
5 output 

// window. This mechanism provides the means for a language engine to 
implement language 

// specific debugging output support. Example: Debug.writeln("Help") in 
JavaScript. 
10 HRESULT DebugOutput( 
[in]LPCOLESTR pstr); 

// Causes a default debugger IDE to be started and a debug session to be 
attached to 

// this application if one does not already exist. This is used to implement just-in- 
15 time 

// debugging. 

HRESULT StartDebugSession(void); 

// Called by the language engine in the context of a thread that has hit a 
breakpoint. 

20 // This method causes the current thread to block and a notification of the 
breakpoint 

// to be sent to the debugger IDE. When the debugger IDE resumes the 
application this 

// method returns with the action to be taken. 
25 U 

II Note: While in the breakpoint the language engine may be called in this thread 
to do 

// various things such as enumerating stack frames or evaluating expressions. 
HRESULT HandleBreakPoint( 
30 [in]BREAKREASON br, 

[out]BREAKRESUMEACTION *pbra); 

// Causes this application to release all references and enter a zombie state. 
Called 

// by the owner of the application generally on shut down. 
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HRESULT Close(void); 

// Returns the current break flags for the application. 
HRESULT GetBreakFlags( 
[out]APPBREAKFLAGS *pabf, 
5 [out] IremoteDebugApplicationThread **pprdatSteppingThread); 

// Returns the application thread object associated with the currently running 
thread. 

HRESULT GetCurrentThread( 
[out] IdebugApplicationThread **pat); 
10 // Creates an IDebugAsyncOperation object to wrap a provided 
IdebugSyncOperation 

// object. This provides a mechanism for language engines to implement 
asynchronous 

// expression and evaluation, etc. without having to know the details of 
15 // synchronization with the debugger thread. See the descriptions for 

// IDebugSyncOperation and IdebugAsyncOperation for more details. 

HRESULT CreateAsyncDebugOperation( 

[in] IdebugSyncOperation *psdo, 

[out] IdebugAsyncOperation **ppado); 
20 // Adds a stack frame sniffer to this application. Generally called by a language 

engine 

// to expose its stack frames to the debugger. It is possible for other entities to 
// expose stack frames. 
HRESULT AddStackFrameSniffer( 
25 [in] IdebugStackFrameSniffer *pdsfs, 

// Returns a cookie that is used to remove this stack frame sniffer 
// from the application. 
[out]DWORD *pdwCookie); 

// Removes a stack frame sniffer from this application. 
30 HRESULT RemoveStackFrameSniffer( 

// The cookie returned by AddStackFrameSniffer. 
[in]DWORD dwCookie); 

// Returns S_OK if the current running thread is the debugger thread. 
// Otherwise, returns S FALSE. 
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HRESULT QueryCurrentThreadlsDebuggerThread(void); 



// Provides a mechanism for the caller to run code in the debugger thread. This is 
// generally used so that language engines and hosts can implement free threaded 
// objects on top of their single threaded implementations. 
5 HRESULT SynchronousCalllnDebuggerThread( 
[in] IdebugThreadCall *pptc, 
[in]DWORD dwParaml, 
[in]DWORD dwParam2, 
[in]DWORD dwParam3); 
10 // Creates a new application node which is associated with a specific 
// document provider. Before it is visible, the new node must be 
// attached to a parent node. 
HRESULT CreateApplicationNode( 
[out] IdebugApplicationNode **ppdanNew); 

15 

// Fire a generic event to the lApplicationDebugger (if any) 

// The semantics of the GUID and lUnknown are entirely application/debugger 

defined 

// This method is currently unimplemented but is here to allow for future 
20 extensions. 

HRESULT FireDebuggerEvent( 
[in]REFGUID hid, 
[in]IUnknown *punk); 

25 // Called by the language engine in the context of a thread that has caused a 
runtime 

// error. This method causes the current thread to block and a notification of the 
error 

// to be sent to the debugger IDE. When the debugger IDE resumes the 
30 application this 

// method returns with the action to be taken. 

// Note: While in the runtime error the language engine may be called in this 
thread to do 

// various things such as enumerating stack frames or evaluating expressions. 
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HRESULT HandleRuntimeError( 

[in] lactiveScriptErrorDebug *pErrorDebug,// the error that occurred 
[in]IActiveScriptSite *pScriptSite,// the script site of the thread 
[out]BREAKRESUMEACTION *pbra,// how to continue execution (stepping etc..) 
5 [out]ERRORRESUMEACTION *perra,// how to handle the error case 
[out]BOOL *pfCallOnScriptError);// if TRUE then engine should call 
IActiveScriptSite::OnScriptError() 

// return TRUE if there is a JIT debugger registered 
10 BOOL FCanJitDebug (); 

// returns TRUE if a JIT debugger is registered to auto-JIT debug dumb hosts 
BOOL FIsAutoJitDebugEnabled (); 

15 // Adds a global expression context provider to this application 
HRESULT AddGlobalExpressionContextProvider( 
[in] IprovideExpressionContexts *pdsfs, 

// Returns a cookie that is used to remove this global expression context provider 
// from the application. 
20 [out]DWORD *pdwCookie); 

// Removes a global expression context provider from this application. 
HRESULT RemoveGlobalExpressionContextProvider( 
//The cookie returned by AddGlobalExpressionContextProvider. 
25 [in]DWORD dwCookie); 

IRemoteDebugApplicationEvents: 

This is the event interface supplied by a debug application: It is always called from 
30 within the debugger thread. 

i 

object, 

uuid(51973C33-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("IRemoteDebugApplicationEvents Interface"), 
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pointer_default(unique) 
1 

interface I RemoteDebugApplication Events : I Unknown 
{ 

HRESULT OnConnectDebugger( 

[in] lapplicationDebugger *pad); 

HRESULT OnDisconnectDebugger(void); 

HRESULT OnSetName( 

[in]LPCOLESTR pstrName); 

HRESULT OnPebugOutput( 

[in]LPCOLESTR pstr); 

HRESULT OnClose(void); 

HRESULT OnEnterBreakPoint( 

[in] IremotePebugApplicationThread *prdat); 

HRESULT OnLeaveBreakPoint( 

[in] IremotePebugApplicationThread *prdat); 

HRESULT OnCreateThread( 

[in] IremotePebugApplicationThread *prdat); 

HRESULT OnPestroyThread( 

[in] IremotePebugApplicationThread *prdat); 

HRESULT OnBreakFlagChange( 

[in]APPBREAKFLAGS abf, 

[in] IremotePebugApplicationThread *prdatSteppingThread); 

k 

IDebugApplicationNode 

Provides the functionality of IdebugDocumentProvider, plus a context within a 
project tree. 

i 

object, 

uuid(51 973C34-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointer_default(unique) 

i 

interface IPebugApplicationNode : IdebugPocumentProvider { 
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HRESULT EnumChildren( 
[out] lenumDebugApplicationNodes **pperddp); 
HRESULT GetParent( 
[out] IdebugApplicationNode **pprddp); 
5 HRESULT SetDocumentProvider( 
[in] IdebugDocumentProvider *pddp); 
HRESULT Close(void); 
HRESULT Attach( 

[in] IdebugApplicationNode *pdanParent); 
10 HRESULT Detach(void); 

1 

IDebugApplicationNodeEvents 

Event interface for DebugApplicationNode object. 
15 [ 

object, 

uuid(51973C35-CB0C-11d0-B5C9-00A0244A0E7A), 
pointerdefault(unique) 

i 

20 interface IDebugApplicationNodeEvents : lUnknown { 

HRESULT onAddChild( 

[in] IdebugApplicationNode *prddpChild); 

HRESULT onRemoveChild( 

[in] IdebugApplicationNode *prddpChild); 
25 HRESULT onDetach(void); 

HRESULTonAttach( 

[in] IdebugApplicationNode *prddpParent); 
1 

30 IDebugThreadCall 

IDebugThreadCall is implemented by a component making a cross-thread call 
using the IDebugThread marshalling implementation in the PPM. It is called by the 
PPM in the desired thread and should dispatches the call to the desired 
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implementation, casting the parameter information passed in the dwParam's to 
the appropriate top. It is, of course, a free-threaded object. 

i 

object, 

5 uuid(51973C36-CB0C-11d0-B5C9-00A0244A0E7A), 
pointer default(unique), 
local 

1 

interface IDebugThreadCall : lUnknown 
10 { 

HRESULT ThreadCallHandler( 
[in] DWORD dwParaml, 
[in] DWORD dwParam2, 
[in] DWORD dwParam3); 
15 } 

IRemoteDebugApplicationThread 

An abstaction representing a thread of execution within a particular application. 
I 

20 object, 

uuid(51973C37-CB0C-11d0-B5C9-00A0244A0E7A), 
pointer_default(unique) 

1 

interface IRemoteDebugApplicationThread : lUnknown 
25 { 

// Returns an operating system dependent identifier associated with the thread. 

// 

// Note: The returned value does not need to be unique across machines. 
HRESULT GetSystemThreadld( 
30 [out]DWORD *dwThreadld); 

// Returns the application object associated with the thread. 

HRESULT GetApplication( 

[out] IremoteDebugApplication **pprda); 
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// Returns an enumerator for the stack frames associated with the thread. Can 
only 

// be called when in a breakpoint. The stack frame enumerator enumerates stack 
frames 

5 // in the most recently called order. 
HRESULT EnumStackFrames( 
[out] lenumDebugStackFrames **ppedsf); 

HRESULT GetDescription( 
10 [out]BSTR *pbstrDescription, 
[out]BSTR *pbstrState); 

// Forces execution to continue as close as possible to the 
// given code context, in the context of the given frame. 
15 // Either of these arguments may be NULL, representing the 
// current frame or context. 
HRESULT SetNextStatement ( 
[in] IdebugStackFrame *pStackFrame, 
[in] IdebugCodeContext *pCodeContext); 

20 

// Thread State flags 

typedef DWORD THREAD. STATE; 

const THREAD STATE THREAD_STATE_RUNNING=0x00000001; 
const THREAD_STATE THREAD STATE_SUSPENDED=Ox00000002; 
25 const THREAD STATE THREAD BLOCKED=0x00000004; 

const THREAD STATE THREAD OUT OF CONTEXT=0x00000008; 

// returns the current state of the thread 
HRESULT GetState ( 
30 [out] DWORD *pState); 

// suspends the thread (increments the suspend count) 
HRESULT Suspend ( 
[out] DWORD *pdwCount); 
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// resumes the thread (decrements the suspend count) 
HRESULT Resume ( 
[out] DWORD *pdwCount); 

5 

// returns the current suspend count of the thread 
HRESULT GetSuspendCount ( 
[out] DWORD *pdwCount); 

1 

10 

IDebugApplicationThread 

An extension of IRemoteDebugApplicationThread that provides non-remotable 
access to the thread. This interface is used by language engines and hosts to 
provide thread synchronization and to maintain thread specific debug state 
15 information. 

I 

object, 

uuid(51 973C38-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
pointerdefault(unique), 
20 local 

1 

interface IDebugApplicationThread : IremoteDebugApplicationThread 

{ 

II Provides a mechanism for the caller to run code in another thread. This is 
25 generally 

// used so that language engines and hosts can implement free threaded objects 
on top 

// of their single threaded implementations. 
HRESULT SynchronousCalllntoThread( 
30 // The interface to be called back in the target thread, 
[in] IdebugThreadCall *pstcb, 

// Three arguments passed to the IDebugThreadCall. 
[in]DWORD dwParaml, 
[in]DWORD dwParam2, 
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[in]DWORD dwParam3); 

// Returns S_OK when this is the currently running thread else S_FALSE is 
returned. 

HRESULT QuerylsCurrentThread(void); 
5 // Returns S_OK when this is the debugger thread. Otherwise, returns S_FALSE. 
HRESULT QuerylsDebuggerThread(void); 
HRESULT SetDescription( 
[in]LPCOLESTR pstrDescription); 
HRESULT SetStateString( 
10 [inlLPCOLESTR pstrState); 

} 
I 

object, local, 

15 uuid(51 973C39-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IDebugCookie Interface"), 
pointer_default(unique) 

1 

interface IDebugCookie : lUnknown 
20 { 

HRESULT SetDebugCookie([in1DWORD dwDebugAppCookie); 



lEnumDebugApplicationNodes 

25 Enumerates Application nodes. Generally used to enumerate child nodes of a 
node associated with an application. Example: a project window. 

i 

object, 

uuid(51973C3a-CB0C-11d0-B5C9-00A0244A0E7A), 
30 helpstring("IEnumDebugApplicationNodes Interface"), 
pointer default(unique) 

1 

interface lEnumDebugApplicationNodes : lUnknown { 
[local] 

114 



1001/047 

HRESULT stdcall Next( 
[in] ULONG celt, 

[out] IDebugApplicationNode **pprddp, 
[out] ULONG *pceltFetched); 

5 

HRESULT Skip( 
[in] ULONG celt); 

HRESULT Reset(void); 

10 

HRESULT Clone( 

[out] lEnumDebugApplicationNodes **pperddp); 
t 

15 lEnumRemoteDebugApplications 

Used to enumerate the running applications on a machine. 

I 

object, 

uuid(51973C3b-CB0C-11dO-B5C9-00A0244A0E7A) T 
20 helpstring("IEnumRemoteDebugApplications Interface"), 
pointer_default(unique) 

i 

interface lEnumRemoteDebugApplications : lUnknown { 
[local] 

25 HRESULT stdcall Next( 
[in] ULONG celt, 

[out] I RemoteDebug Application **ppda, 
[out] ULONG *pceltFetched); 
HRESULT Skip( 
30 [in] ULONG celt); 

HRESULT Reset(void); 

HRESULT Clone( 
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[out] lEnumRemoteDebugApplications **ppessd); 
1 

lEnumRemoteDebugApplicationThreads 

5 Used to enumerate the running threads in an application. 

i 

object, 

uuid(51 973C3C-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
helpstring("IEnumRemoteDebugApplicationThreads Interface"), 
10 pointer_default(unique) 

i 

interface lEnumRemoteDebugApplicationThreads : lUnknown { 
[local] 

H RESULT _stdcall Next( 
15 [in] ULONG celt, 

[out] IRemoteDebugApplicationThread **pprdat, 
[out] ULONG *pceltFetched); 

HRESULT Skip( 
20 [in] ULONG celt); 

HRESULT Reset(void); 

HRESULT Clone( 
25 [out] lEnumRemoteDebugApplicationThreads **pperdat); 

} 

IDebugFormatter 

I Debug Formatter allows a language or IDE to customize the conversion between 
30 variants or VARTYPES and strings. This interface is used by the ITypelnfo- 
>IDebugProperty mapping implementation. 

i 

object, 

uuid(51 973C3d-CB0C-1 1 d0-B5C9-00A0244A0E7A), 
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helpstringC'IDebugFormatter Interface"), 

pointer_default(unique), 

local 

1 

5 interface I Debug Formatter : lUnknown 

{ 

HRESULT GetStringForVariant([in] VARIANT *pvar, [out] BSTR *pbstrValue); 
HRESULT GetVariantForString([in] LPCOLESTR pwstrValue, [out] VARIANT 
*pvar); 

10 HRESULT GetStringForVarType([in] VARTYPE vt, [in] TYPEDESC 
*ptdescArrayType, [out] BSTR *pbstr); 

1 

ISimpleConnectionPoint 

15 This interface is the "IDispatchEx" of event interfaces. It provides a simple way for 
describing and enumerating the events fired on a particular connection pointan 
also for hooking up an IDispatch to those events. This interface will be available 
as extended info via the IDebugProperty interface on objects which support 
events. For simplicity, this interface only works with dispinterfaces. 

20 [ 

object, 

uuid(51973C3e-CB0C-11d0-B5C9-00A0244A0E7A), 
helpstring("ISimpleConnectionPoint Interface"), 
pointerdefault(unique), 
25 local 

] 

interface ISimpleConnectionPoint : lUnknown 

i 

// Return the number of events exposed on this interface 
30 HRESULT GetEventCount([out] ULONG *pulCount); 

// Return the DISPID and NAME for "cEvents" events, starting at "iEvent". 
// The number of 

//- Returns S_OK if all of the requested elements were returned. 
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//- Returns S FALSE if the enumeration finished and the 



//requested number of elements was not available. 

//(Unavailable elements will be returned as DISPID_NULL and a null bstr.) 

//- Returns EJNVALIDARG (or other error status) if no elements could be fetched 

5 

HRESULT DescribeEvents( 
[in] ULONG iEvent,// starting event index 
[in] ULONG cEvents,// number of events to fetch info for 
[out, size_is(cEvents), length_is(*pcEventsFetched)] 
10 DISPID *prgid,// DISPIDs of the events 

[out, size is(cEvents), length is(*pcEventsFetched)] 
BSTR *prgbstr, 

[out] ULONG *pcEventsFetched 
);// names of the events 

15 

HRESULT Advisettinl IDispatch *pdisp, [out] DWORD* pdwCookie); 
HRESULT Unadvise([in1 DWORD dwCookie); 

20 IDebugHelper 

Serves as a factory for object browers and simple connection points. 
cpp quote( "EXTERN C const CLSID CLSID DebugHelper;") 

I 

object, 

25 uuid(51973C3f-CB0C-11d0-B5C9-00A0244A0E7A) > 
helpstring("IDebugHelper Interface"), 
pointerdefault(unique), 
local 

1 

30 interface IDebugHelper : lUnknown 

// Returns a property browser that wraps a VARIANT 
HRESULT CreatePropertyBrowser( 



[in] VARIANT *pvar, // root variant to browse 
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[in] LPCOLESTR bstrName, // name to give the root 

[in] IdebugApplicationThread *pdat, // thread to request properties on or NULL 
[out] IDebugProperty**ppdob); 

5 // Returns a property browser that wraps a VARIANT, and allows for custom 
conversion 

// of variants or VARTYPEs to strings 
HRESULT CreatePropertyBrowserEx( 
[in] VARIANT *pvar,// root variant to browse 
10 [in] LPCOLESTR bstrName,// name to give the root 

[in] IdebugApplicationThread *pdat, // thread to request properties on or NULL 
[in] IdebugFormatter *pdf,// provides custom formatting of variants 
[out] IDebugProperty**ppdob); 

15 // Returns an event interface that wraps the given IDispatch (see 

ISimpleConnectionPoint) 

HRESULT CreateSimpleConnectionPoint( 

[in] IDispatch *pdisp, 

[out] IsimpleConnectionPoint **ppscp); 
20 K 

lEnumDebugExpressionContexts 

i 

object, 

25 uuid(51 973C40-CB0C-1 1 d0-B5C9-00A0244A0E7A), 

helpstring("lEnumDebugExpressionContexts Interface"), 
pointer_default(unique) 

] 

interface lEnumDebugExpressionContexts : lUnknown 
30 { 

[local] 

HRESULT _stdcall Next( 
finl ULONG celt, 

[out] IdebugExpressionContext **ppdec, 
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[out] ULONG *pceltFetched); 
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HRESULT Skip( 



finl ULONG celt); 
HRESULT Reset(void); 

5 

HRESULT Clone( 

[out] lEnumDebugExpressionContexts **ppedec); 
} 

10 IProvideExpressionContexts 

Provides a means for enumerating expression contexts known by a certain 
component. Generally implemented by each script engine. Used by the process 
debug manager to find all global expression contexts associated with a given 
thread. Note: This interface is called from within the thread of interest. It is up to 
15 the implementor to identify the current thread and return an appropriate 
enumerator. 

i 

object, 

uuid(51973C41-CB0C-11d0-B5C9-00A0244A0E7A), 
20 pointerdefault(unique) 

i 

interface IProvideExpressionContexts : I Unknown 

{ 

// Returns an enumerator of expression contexts. 
25 HRESULT EnumExpressionContexts( 

[out] lenumDebugExpressionContexts **ppedec); 

i 
i 

30 uuid(78a51821-51f4-11d0-8f20-00805f2cd064), 
version(1 .0), 

helpstring("ProcessDebugManagerLib 1 .0 Type Library") 
1 

library ProcessDebugManagerLib 
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i 

importlib("stdole2.tlb"); 



interface 


lActiveScriptDebug; 


interface 


lActiveScriptErrorDebug; 


interface 


lActiveScriptSiteDebug; 


interface 


lApplicationDebugger; 


interface 


1 ApplicationDebuggerU 1 ; 


interface 


IDebugApplication; 


interface 


IDebugApplicationNode; 


interface 


IDebugApplication NodeEvents; 


interface 


IDebugApplicationThread; 


interface 


IDebugAsyncOperation; 


interface 


IDebugAsyncOperationCallBack; 


interface 


IDebugCodeContext; 


interface 


IDebugCookie; 


interface 


IDebugDocument; 


interface 


1 Debug Docu mentContext; 


interface 


IDebugDocumentHelper; 


interface 


IDebugDocumentHost; 


interface 


IDebugDocumentlnfo; 


interface 


IDebugDocumentProvider; 


interface 


1 Debug Docu mentText; 


interface 


1 Debug Docu mentTextAuthor; 


interface 


IDebugDocumentTextEvents; 


interface 


1 Debug Docu mentTextExternal Author; 


interface 


IDebugExpression; 


interface 


IDebugExpressionCallBack; 


interface 


IDebugExpressionContext; 


interface 


IDebugFormatter; 


interface 


IDebugHelper; 


interface 


IDebugSessionProvider; 


interface 


IDebugStackFrame; 


interface 


IDebugStackFrameSniffer; 
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interface IDebugStackFrameSnifferEx; 

interface IPebugSyncOperation; 

interface IDebugThreadCall; 

interface lEnumDebugApplicationNodes; 
5 interface lEnumDebugCodeContexts; 

interface lEnumDebugExpressionContexts; 

interface lEnumDebugStackFrames; 

interface lEnumRemotePebugApplications; 

interface lEnumRemotePebugApplicationThreads; 
10 interface IMachinePebugManager; 

interface IMachinePebugManagerCookie; 

interface IMachinePebugManagerEvents; 

interface IProcessPebugManager; 

interface IProvideExpressionContexts; 
15 interface IRemotePebugApplication; 

interface IRemotePebugApplicationEvents; 

interface IRemotePebugApplicationThread; 

interface ISimpleConnectionPoint; 



20 [ 

uuid(78a51 822-51 f4-11d0-8f20-00805f2cd064), 
helpstringC'ProcessPebugManager Class") 

i 

coclass ProcessPebugManager 
25 { 

[default] interface IProcessPebugManager; 

i; 
i 

30 uuid(0BFCC060-8C1 D-1 1d0-ACCD-00AA0060275C), 
helpstring("DebugHelper Class") 

1 

coclass DebugHelper 
i 
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[default] interface IDebugHelper; 

// CDebugDocumentHelper 

5 U 

II The CDebugDocumentHelper makes it much easier for an ActiveScripting 
// host or scripting engine to implement the IDebugDocument interfaces. 

IJ_ 

If Given the source text and (optionally) script blocks for a host's 
10 // document, CDebugDocumentHelper provides implementations for 
//the debug document interfaces, including: 

IJ_ 

//- IDebugDocumentText 
//- IDebugDocumentTextAuthor (for authoring) 
15 //- IDebugDocumentContext 

U 

II This class supports aggregation, so the host may provide a controlling 
// unknown to CoCreatelnstance for extensibility. 

H 

20 // This class fires events on IDebugDocumentTextEvents, so the host 
// can monitor all changes to the document via that interface. 
cpp_quote( "EXTERNLC const CLSID CLSID^CDebugDocumentHelper;") 

I 

uuid(83B8BCA6-687C-1 1 D0-A405-00AA0060275C), 
25 helpstring("DebugDocumentHelper Class") 

1 

coclass CDebugDocumentHelper 

i 

[default] interface IDebugDocumentHelper; 
30 interface IDebugDocumentProvider; 
interface IDebugDocument; 
interface IDebugDocumentText; 
interface IDebugDocumentTextAuthor; 
interface IConnectionPointContainer; 
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[default, source] interface IDebugDocumentTextEvents; 

t 
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ACTIVE DEBUGGING ENVIRONMENT FOR APPLICATIONS CONTAINING 
COMPILED AND INTERPRETED PROGRAMMING LANGUAGE CODE 

Abstract 

5 

An active debugging environment for debugging a virtual application that 
contains program language code from multiple compiled and/or interpreted 
programming languages. The active debugging environment is language neutral 
and host neutral, where the host is a standard content centric script host with 

1 0 language engines for each of the multiple compiled and/or interpreted 

programming languages represented in the virtual application. The active 
debugging environment user interface can be of any debug tool interface design. 
The language neutral and host neutral active debugging environment is 
facilitated by a process debug manager that catalogs and manages application 

15 specific components, and a machine debug manager that catalogs and manages 
the various applications that comprise a virtual application being run by the script 
host. The process debug manager and the machine debug manager act as an 
interface between the language engine specific programming language details 
and the debug user interface. 
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